Errores

Todos los errores usan el formato de OpenAI, así que los SDK lanzan sus excepciones habituales:

Para la forma exacta de cada petición y respuesta, con ejemplos en curl, Python y Node, consulta la Referencia de la API.

{
  "error": {
    "message": "'temperature' must be between 0 and 2.",
    "type": "invalid_request_error",
    "param": "temperature",
    "code": "invalid_value"
  }
}

type es uno de invalid_request_error, permission_error, billing_error, rate_limit_error o server_error. param nombra el campo problemático cuando lo hay. La cabecera x-request-id va en todas las respuestas; cítala cuando escribas a soporte. Los mensajes de error están en inglés.

400: petición incorrecta

code	Significado
invalid_json	el cuerpo no es JSON válido o no se pudo leer
no_model_allowed	una petición auto cuyo acceso a modelos no le deja a auto ningún modelo que pueda usar. El mensaje dice qué nivel revisar: account (cuenta), organization (organización), project (proyecto) o key (key). Consulta Acceso a modelos
missing_messages	falta messages o está vacío (si falta model, es auto)
too_many_messages, too_many_tools	más de 4096 mensajes o 256 herramientas
invalid_value	un campo está fuera de rango o mal formado; param dice cuál
unsupported_parameter	un campo que Zabio no implementa (n mayor que 1, logprobs, audio, prediction, web_search_options, modalities distintas de texto, el rol antiguo function); tools enviadas a un modelo que no puede recibirlas a través de Zabio (hoy gpt-6-astra)
invalid_image_url	una imagen no se pudo descargar o no está permitida; consulta Chat completions
byok_key_invalid	el proveedor rechazó la key propia de tu organización; actualízala en Facturación, keys de proveedor. Zabio nunca recurre a su propia key en ese caso
upstream_invalid_request	el proveedor rechazó la petición; el mensaje incluye el motivo del proveedor
unsupported_for_model	el modelo que nombraste no puede hacer lo que pide la petición; param nombra el campo (jev-1.13.0 solo responde preguntas tipadas desde un json_schema, nunca texto, herramientas, imágenes ni un stream)
conversation_mismatch, conversation_too_large, context_length_exceeded	Responses API; consulta Responses API

401: autenticación

code: invalid_api_key cuando la key falta, es incorrecta o está revocada; el mensaje dice cuál. Las keys se envían como Authorization: Bearer zb_live_....

code: key_expired cuando ha pasado la caducidad de la key. El mensaje, en inglés como todos los de la API, dice cuándo caducó: "This API key expired on 2026-11-01 00:00 UTC. Create a new key or change its expiration in the web app." La caducidad de una key se fija al crearla o después en su panel de edición; quien la creó recibe un correo 7 días antes. Las respuestas en segundo plano y los lotes que la key dejó en cola antes de caducar terminan con el mismo código.

402: sin créditos

{"error": {"message": "Your organization has no credits left. Add credits at zabio.ai/billing to continue.", "type": "billing_error", "code": "insufficient_credits"}}

Se devuelve antes de cualquier trabajo con el proveedor, solo cuando un saldo cero significa que no hay servicio: la organización está configurada para detenerse al llegar a cero, o es la segunda organización de una persona, que no tiene plan Free. Cualquier otra organización en cero funciona con los límites de Free (consulta Facturación, “El plan Free”) y recibe los códigos free_tier_* de abajo. La cabecera x-zabio-balance-micros lleva el saldo. Un modelo con nombre servido con tu propia key de proveedor no se rechaza; auto sí, tengas las keys que tengas, porque el clasificador se ejecuta con la key de Zabio. Un lote o una response en segundo plano cuyo coste estimado supera el saldo disponible también se rechaza con este código.

403: no permitido

code	Significado
insufficient_scope	la key no tiene el scope para este endpoint (chat, embeddings o conversations)
organization_suspended	la organización está suspendida
conversations_closed	las conversaciones guardadas están cerradas para esta organización
free_tier_model	la petición nombra un modelo que no está en la lista de modelos gratuitos mientras la organización funciona con los límites de Free. El mensaje es “Top up your account to unlock this model” con el enlace de recarga; auto sigue funcionando y elige entre los modelos gratuitos. GET /v1/models marca los modelos bloqueados con zabio.availability: locked
free_tier_limit con param members o api_keys	los topes de cuenta del plan Free, en la API del panel: un miembro y dos API keys hasta la primera recarga

404: no encontrado

model_not_found: el modelo no existe, o un nivel del acceso a modelos de la key (la cuenta, la organización, el proyecto o la key) no lo permite; una línea auto que un nivel desmarcó se rechaza igual. La Responses API añade previous_response_not_found, conversation_not_found y response_not_found.

413: demasiado grande

payload_too_large: el cuerpo supera los 32 MB.

429: demasiadas peticiones

Todos los 429 llevan una cabecera Retry-After con los segundos a esperar. Existen cuatro límites:

code	Ámbito	Detalles
rate_limit_exceeded	API key	el cupo de peticiones por minuto o de tokens por minuto de la key está vacío. Por defecto: 600 peticiones y 200,000 tokens por minuto; se configura por key. El cupo de tokens se cobra por adelantado con la estimación de entrada más el presupuesto de salida, limitado a lo que el modelo servido puede producir, y se ajusta al uso real tras la llamada; un max_tokens muy por encima de lo que la tarea necesita puede agotar el límite antes de tiempo, así que ponlo cerca de lo que necesitas. Las cabeceras x-ratelimit-limit-*, x-ratelimit-remaining-* y x-ratelimit-reset-* para requests y tokens van en todas las respuestas
quota_exceeded	key o miembro (nivel de organización)	se alcanzó el límite de gasto de la key en su periodo (un día, una semana desde el lunes o un mes, desde las 00:00 UTC, o toda la vida de la key), o la cuota mensual del miembro que creó la key. El mensaje dice cuándo se reinicia, por ejemplo "This API key's spend limit of 5.00 USD has been reached. It resets on 2026-10-19 at 00:00 UTC.". Van las cabeceras x-zabio-quota-scope (key o member), x-zabio-quota-limit y x-zabio-quota-remaining
ip_rate_limit_exceeded	dirección del cliente	demasiadas peticiones desde una misma dirección, comprobado antes de la autenticación. Por defecto 300 por minuto. Las cabeceras x-ratelimit-*-ip solo van en el rechazo
upstream_rate_limited	proveedor	el proveedor está limitando y se agotaron todos los fallbacks
free_tier_limit	organización, con los límites de Free	se alcanzó uno de los límites de Free; param y la cabecera x-zabio-free-limit lo nombran: requests_per_day (100 peticiones correctas por día UTC; Retry-After es el tiempo hasta las 00:00 UTC), requests_per_minute (20), daily_cost (el límite diario de uso razonable; se reinicia a las 00:00 UTC), input_tokens (la petición tiene más de 16,000 tokens de entrada; sin Retry-After, envía una petición más corta) o max_tokens (un max_tokens explícito por encima de 2,000; bájalo o déjalo sin fijar). El mensaje dice qué límite, cuándo se reinicia y que una recarga quita todos los límites. Las cabeceras de límite de Free (x-ratelimit-*-requests-day y el cupo del minuto en x-ratelimit-*-requests) van en todas las respuestas Free, rechazos incluidos. Consulta Facturación

rate_limit_exceeded, quota_exceeded y free_tier_limit usan type: rate_limit_error.

5xx: lado del servidor

Estado	code	Significado
500	internal_error	una condición inesperada; la causa nunca va en el cuerpo
502	upstream_error	el proveedor devolvió un error o una respuesta ilegible tras los reintentos y fallbacks. Retry-After: 5 cuando tiene sentido reintentar
503	no_provider_available	ahora mismo no hay ningún proveedor sano para esta petición; Retry-After: 5
503	vendor_unavailable	la llamada nombró un modelo de un proveedor que ahora mismo no está disponible a través de Zabio; llama a otro modelo o a auto, o reintenta más tarde; Retry-After: 5
503	auth_unavailable, billing_unavailable, conversations_unavailable	una dependencia de Zabio no está disponible temporalmente
503	free_tier_unavailable	no se pudieron leer los contadores de los límites de Free, así que una llamada gratuita se rechaza en lugar de servirse sin medir; reintenta en breve. Las llamadas de pago no se ven afectadas. También es la respuesta de GET /v1/public/free-tier cuando la lista no se puede leer
504	upstream_timeout	el proveedor no respondió a tiempo; Retry-After: 5

Errores tras un 200 ya confirmado (llamadas largas)

Una llamada que Zabio ha mantenido viva más de 90 segundos (ver “Llamadas largas” en las guías de chat completions y de Responses) ya tiene su estado 200 en la conexión cuando el proveedor falla, así que el error viaja en el cuerpo:

Llamada	Forma
chat completions, sin streaming	un chat.completion con choices: [] y un objeto error al lado (message, type, code)
chat completions, con streaming	data: {"error": {"message", "type", "code"}} y después data: [DONE]
Responses, sin streaming	el objeto response con status: "failed" y error: {"code", "message"}
Responses, con streaming	un evento response.failed con ese objeto

Los valores de code son los mismos de las tablas anteriores. Comprueba error siempre que choices esté vacía o status sea failed.

Errores de proveedor y fallback

Cuando un proveedor falla, Zabio reintenta con el siguiente modelo elegible según las reglas de enrutado (hasta 3 intentos; los modelos explícitos siguen zabio.fallback). Solo cuando se agotan todas las opciones ves un error de proveedor. El cuerpo del proveedor nunca te llega; x-zabio-vendor nombra al proveedor que falló y el mensaje incluye su motivo en los 400. El contenido que el proveedor se niega a producir vuelve como una respuesta normal con finish_reason: "content_filter", no como un error.

Durante el streaming, un fallo después de que el stream haya empezado se comunica como un objeto error dentro de un chunk (chat completions) o como un evento error (Responses API), y el stream termina.

Dos códigos más en la Responses API

• missing_field (400): falta un campo obligatorio como input, o el role, content o call_id de un item. Si falta model, es auto.
• previous_response_not_found y conversation_not_found (404) en POST /v1/responses; response_not_found (404) aplica a GET y DELETE /v1/responses/{id}.

La lista completa por endpoint está en la referencia de la API.