Errores
Los errores se devuelven como JSON con un estado 4xx o 5xx. El formato sigue el protocolo del endpoint, así que los SDK de OpenAI y Anthropic lanzan sus clases de excepción habituales. Hay un caso distinto: cuando una solicitud sin streaming ya lleva 90 segundos en curso, un error posterior llega en el cuerpo de una respuesta 200 (consulta Solicitudes largas).
Códigos de error
| Código | Estado | Cuándo ocurre |
|---|---|---|
invalid_api_key | 401 | Falta la clave de API, tiene un formato incorrecto, es desconocida, está revocada o venció. El mensaje de una clave vencida indica su fecha de vencimiento. |
account_suspended | 403 | La cuenta está suspendida. Todas sus claves se rechazan hasta que termine la suspensión; contacta a soporte. |
account_banned | 403 | La cuenta está bloqueada. Sus claves se revocan y el crédito restante se pierde. |
card_network_blocked | 403 | Recarga con tarjeta rechazada: la solicitud provino de una red VPN, Tor o de centro de datos. |
card_account_risk | 403 | Recarga con tarjeta rechazada: el análisis antifraude de Stripe calificó la cuenta con el riesgo más alto, así que no puede recargar con tarjeta. Las recargas con cripto siguen funcionando. |
model_not_found | 404 | El ID de model no corresponde a un modelo habilitado. Consulta la lista de ID con GET /v1/models. |
unsupported_content | 400 | La solicitud contiene una parte que el modelo no acepta: una parte de imagen o video para un modelo cuyas input_modalities no la incluyen; un video que no es una URL https:// (incluido el video en base64), o una URL de imagen que no es https://, http:// ni data:; o una parte de audio o de archivo, que ningún modelo acepta. |
content_policy_violation | 400 | El control de seguridad automatizado bloqueó la solicitud. |
stateless_only | 400 | Una solicitud a /v1/responses estableció previous_response_id o background: true. Envía la conversación completa en input, sin background. |
invalid_request | 400 | El cuerpo no pasó la validación (por ejemplo, falta max_tokens en /v1/messages; n distinto de 1; más de 4 prompts en un array prompt de /v1/completions; service_tier: "priority" en un modelo sin nivel prioritario; un tipo de herramienta distinto de function (o de custom y namespace en /v1/responses); o /v1/completions con un modelo que no tiene endpoint de completions), el cuerpo no se recibe a tiempo (estado 408) o supera los 16 MiB (estado 413), o el modelo lo rechazó, por ejemplo, por un prompt más largo que la ventana de contexto o por más imágenes de las que admite. Los rechazos del modelo conservan su propio estado 4xx y su mensaje. |
insufficient_balance | 402 | Tu saldo no alcanza para cubrir la entrada estimada más un presupuesto de salida de al menos 256 tokens. Recarga saldo. |
key_spend_cap_reached | 402 | La retención de esta solicitud, sumada al gasto liquidado de la clave y a sus otras solicitudes en curso, superaría su tope de gasto diario, mensual o total. |
rate_limit_exceeded | 429 | Demasiadas solicitudes en este minuto para la clave o para la cuenta, demasiadas solicitudes simultáneas para la cuenta, demasiado del presupuesto de cuerpos en curso ocupado por las cargas grandes de la cuenta o, en una cuenta de prueba, más de 2 cuentas de prueba que envían solicitudes desde la misma red en una hora. Los límites por minuto y el límite de red de las cuentas de prueba envían Retry-After. |
capacity_exhausted | 429 | Todas las réplicas del modelo siguieron ocupadas durante 30 s de reintentos (las cuentas de prueba no tienen reintentos y fallan de inmediato), o el gateway está brevemente al límite de su capacidad o reiniciándose (estado 503). Espera los segundos que indica Retry-After. Un modelo sin ninguna capacidad de servicio devuelve model_unavailable en su lugar. No se cobra nada. |
model_unavailable | 503 | El modelo no tiene capacidad de servicio en este momento, por ejemplo, mientras se reemplazan sus GPU. La solicitud falla de inmediato, para todas las cuentas, sin reintentos. Retry-After indica los segundos que faltan para que volvamos a comprobar el modelo; vuelve a intentarlo entonces o usa otro modelo. No se cobra nada. |
safety_unavailable | 503 | El control de seguridad agotó el tiempo de espera o falló, así que la solicitud se rechazó en lugar de enviarse sin revisar. Vuelve a intentarlo en breve. |
card_network_check_unavailable | 503 | Recarga con tarjeta rechazada porque la comprobación de red no está disponible por un momento; vuelve a intentarlo o paga con cripto. |
upstream_error | 502 | Falló el backend del modelo, o la solicitud se detuvo al alcanzar el límite de 10 minutos, tras 2 minutos sin salida del modelo o por un reinicio. Un fallo interno inesperado devuelve este código con estado 500, una interrupción breve o un reinicio de nuestro lado lo devuelve con estado 503 y Retry-After, y un fallo del backend lo devuelve con estado 502, en todos los casos antes de enviar ninguna respuesta. Los límites de tiempo solo se alcanzan más tarde: terminan un stream, y una respuesta sin streaming que sigue en curso después de 90 segundos ya se envió con estado 200, así que este error, por un límite de tiempo o por cualquier otra causa, llega entonces en su cuerpo sin Retry-After (consulta Solicitudes largas). Si el modelo aún no había generado ninguna salida, no se cobra nada; vuelve a intentar la solicitud. Si ya generó salida, se cobra la entrada estimada más la salida generada antes del fallo o la detención. Un cliente que se desconecta nunca recibe este error; se le cobra la entrada estimada aunque no se haya generado ninguna salida. |
Lo que bloquea content_policy_violation se define en la política de uso aceptable.
Formato de OpenAI
Lo usan /v1/chat/completions, /v1/responses, /v1/models y /v1/balance. code es uno de los códigos anteriores. Por ejemplo:
{
"error": {
"type": "rate_limit_error",
"code": "capacity_exhausted",
"message": "All model replicas are busy. Retry shortly."
}
}Formato de Anthropic
Lo usa /v1/messages. Este formato no tiene campo code, así que lee el estado HTTP y error.type. Por ejemplo:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "max_tokens is required."
}
}Tipos de error por estado
| Estado | error.type de OpenAI | error.type de Anthropic |
|---|---|---|
| 400 | invalid_request_error | invalid_request_error |
| 401 | authentication_error | authentication_error |
| 402 | insufficient_quota | billing_error |
| 403 | permission_error | permission_error |
| 404 | not_found_error | not_found_error |
| 408 | invalid_request_error | invalid_request_error |
| 413 | invalid_request_error | request_too_large |
| 429 | rate_limit_error | rate_limit_error |
| 500, 502, 503 | api_error | api_error |
Encabezados
x-request-idestá en todas las respuestas, incluidos los errores. Inclúyelo cuando contactes a soporte.Retry-After(en segundos) acompaña acapacity_exhausted, amodel_unavailable(los segundos que faltan para que volvamos a comprobar el modelo, como máximo 15), arate_limit_exceededpor minuto y por red de prueba, y a un 503upstream_error(una interrupción breve o un reinicio de nuestro lado).
Cuándo reintentar
| Error | Qué hacer |
|---|---|
capacity_exhausted | Espera Retry-After segundos y reintenta. Un 429 significa que las solicitudes de pago ya se reintentaron durante hasta 30 segundos; un 503 significa que el gateway estaba al límite de su capacidad o reiniciándose y la solicitud nunca llegó a un modelo. |
model_unavailable | Espera Retry-After segundos y reintenta: es cuando volvemos a comprobar el modelo. La solicitud falló de inmediato, sin reintentos, porque el modelo no tenía capacidad de servicio. Una interrupción así puede durar varios minutos, así que, si el error persiste, cambia a otro modelo. |
rate_limit_exceeded | Para el límite por minuto, espera Retry-After segundos. Para el límite de solicitudes simultáneas, reintenta cuando termine una de tus solicitudes en curso. Para el límite de cuentas de prueba por red, espera Retry-After segundos o recarga saldo: las cuentas de pago no tienen este límite. |
safety_unavailable | Reintenta después de unos segundos. El control de seguridad falla de forma cerrada: cuando no puede ejecutarse, la solicitud se rechaza en lugar de reenviarse sin verificar. |
upstream_error | Con estado 503, espera Retry-After segundos y reintenta. En los demás casos, incluido un cuerpo 200, reintenta con backoff exponencial. |
insufficient_balance, key_spend_cap_reached | Recarga saldo, o sube el tope o espera a que se reinicie. Reintentar antes no sirve. |
| Otros 4xx | Corrige la solicitud. Si la reintentas sin cambios, devuelve el mismo error. |
Las solicitudes fallidas que no produjeron salida no se cobran, incluidas las detenidas por un límite de tiempo o un reinicio. La única excepción es una desconexión de tu cliente, que se cobra por la entrada estimada aunque no se haya generado salida. Una solicitud que falla o se detiene después de que el modelo generó salida se cobra por la entrada estimada más la salida generada antes de que terminara. Consulta cómo se cobra una solicitud.
Solicitudes largas
Una respuesta sin streaming es un único objeto JSON, que está listo cuando el modelo termina. Si está listo dentro de los 90 segundos posteriores a la llegada de la solicitud, se envía como de costumbre: un resultado o un error, con su propio estado y sus propios encabezados.
Una respuesta que no está lista a los 90 segundos se empieza a enviar en ese momento, para que la conexión siga abierta: se envían el estado 200 y Content-Type: application/json (con x-request-id), y el cuerpo empieza con un salto de línea (\n), seguido de otro cada 15 segundos. Cuando el resultado está listo, le sigue el objeto JSON y la respuesta termina. Los parsers de JSON omiten los espacios en blanco antes de un valor, así que los SDK de OpenAI y Anthropic, JSON.parse, json.loads y response.json() la leen sin cambios. Así, una solicitud sin streaming dispone del límite de tiempo completo de 10 minutos.
Una vez que el estado es 200, un error ya no puede cambiarlo. Un error posterior (el límite de tiempo de 10 minutos, 2 minutos sin salida del modelo, un fallo del backend o un reinicio) llega en el cuerpo 200 como el objeto de error habitual: el formato de OpenAI, o el formato de Anthropic en /v1/messages. Con él no se puede enviar un encabezado Retry-After. Un cliente que solo verifica el estado no verá el error, así que revisa si el cuerpo tiene un miembro error de nivel superior. El cobro es el mismo que para cualquier otra solicitud fallida o detenida (ver arriba), y cerrar la conexión mientras esperas cuenta como una desconexión del cliente.
El streaming con "stream": true sigue siendo una buena opción para generaciones largas: ves los primeros tokens pronto y la salida a medida que se genera. No es necesario para evitar que se agote el tiempo de espera.