Lección 3 de 4 · 8 minutos

Cuando falla una solicitud

Decide según el código de error y el estado, y reintenta solo los errores que pueden funcionar más tarde.

Todos los errores de Phaseo tienen el mismo cuerpo JSON en todos los endpoints. El objeto error tiene la forma que ya leen los SDK compatibles con OpenAI:

{
  "error": {
    "code": "insufficient_funds",
    "message": "...",
    "type": "insufficient_quota",
    "param": null
  },
  "generation_id": "G-...",
  "status_code": 402
}

Decide según error.code y el estado HTTP, nunca según el texto del mensaje. Registra siempre generation_id.

EstadoCódigo habitualQué hacer
400validation_error, model_requiredCorrige la solicitud. error.param indica el campo.
401unauthorisedComprueba la clave y la cabecera Authorization.
402insufficient_fundsAñade créditos o usa phaseo/free.
403guardrail_blockedCambia la solicitud o el guardrail.
404not_foundComprueba la ruta y el ID.
410model_retiredCambia a replacement_model.
429rate_limit_exceeded, key_limit_exceededEspera lo que indique Retry-After y reintenta.
5xxupstream_error, gateway_errorReintenta con espera exponencial.

No reintentes sin cambios los errores 4xx distintos de 429: volverán a fallar. Con 429, espera lo que indique Retry-After (segundos o una fecha HTTP), o usa espera exponencial con jitter. Un key_limit_exceeded sin Retry-After no se restablece solo, así que no lo reintentes. Reintenta los 5xx solo cuando repetir la llamada sea seguro, y fija un número máximo de intentos y un plazo total.

Comprueba lo que has aprendido

Tu solicitud devuelve 401 con el código unauthorised. ¿Qué debe hacer tu código?

Ponlo en práctica

Un script por lotes envía 500 solicitudes en un bucle. A mitad, las respuestas empiezan a llegar como 429 con una cabecera Retry-After: 20. ¿Qué cambias?

Mostrar la respuesta

Haz que el script respete Retry-After: espera unos 20 segundos antes de reintentar, y usa espera exponencial con jitter cuando falte la cabecera. Comprueba también error.code: rate_limit_exceeded se restablecerá, pero un key_limit_exceeded sin Retry-After no, así que no tiene sentido reintentarlo.

Idea clave

Decide según error.code y el estado, corrige los errores 4xx y reintenta con espera exponencial solo los 429 y los 5xx seguros.

Enlaces relacionados

El progreso se guarda en este navegador.

Revisado por última vez el 17 de noviembre de 2026