Errores
Los errores vienen con un código HTTP y un cuerpo así:
{ "error": { "message": "Saldo insuficiente. Recarga desde S/20 para seguir.", "code": "insufficient_balance" } }El message está escrito para personas; para decidir en tu código, usa el code.
| HTTP | code |
Qué pasó | Qué hacer |
|---|---|---|---|
| 400 | invalid_model |
El modelo no existe | Usa colibri, aguila o apu |
| 400 | — | La petición está mal formada | Revisa el JSON y los mensajes |
| 401 | no_auth |
No mandaste llave | Añade Authorization: Bearer … |
| 401 | invalid_key |
Llave inválida o revocada | Crea una nueva en API y llaves |
| 402 | insufficient_balance |
Sin saldo | Recarga desde S/20 |
| 403 | upgrade |
Tu plan no permite la API o esa llave | Pasa a un plan de pago |
| 429 | rate_limited |
Demasiadas peticiones | Espera lo que dice Retry-After |
| 429 | monthly_limit |
Llave de plan: llegaste al tope del período | Espera al reinicio o mejora tu plan |
| 502 | — | Jeimy no pudo responder | Reintenta |
| 503 | — | Servicio no disponible por un momento | Reintenta en unos minutos |
En /v1/messages los errores llegan en la forma de Anthropic (authentication_error, invalid_request_error, rate_limit_error…).
Reintentar
Sección titulada «Reintentar»- Reintenta los 429, 502 y 503, con una espera que crezca en cada intento.
- No reintentes los 400, 401, 402 y 403: la misma petición va a fallar igual hasta que cambies algo.