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.
| Estado | Código habitual | Qué hacer |
|---|---|---|
400 | validation_error, model_required | Corrige la solicitud. error.param indica el campo. |
401 | unauthorised | Comprueba la clave y la cabecera Authorization. |
402 | insufficient_funds | Añade créditos o usa phaseo/free. |
403 | guardrail_blocked | Cambia la solicitud o el guardrail. |
404 | not_found | Comprueba la ruta y el ID. |
410 | model_retired | Cambia a replacement_model. |
429 | rate_limit_exceeded, key_limit_exceeded | Espera lo que indique Retry-After y reintenta. |
5xx | upstream_error, gateway_error | Reintenta 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 respuestaOcultar 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
error.code y el estado, corrige los errores 4xx y reintenta con espera exponencial solo los 429 y los 5xx seguros.Enlaces relacionados
Revisado por última vez el 17 de noviembre de 2026