Inicio / Cuando algo falla

Errores de API y limite de tasa

Una llamada a la API puede fallar de varias maneras distintas: un error 400 o 404 casi siempre señala una solicitud mal formada que debe corregirse antes de cualquier nuevo intento, salvo el caso particular de un 400 devuelto por haber alcanzado un límite de gasto, mientras que un error 429 solo se resuelve esperando si lleva una cabecera Retry-After, lo cual no es el caso de un límite de gasto alcanzado.

Un error devuelto por la API de Anthropic lleva un código de estado que distingue causas muy diferentes. Un error 400, invalid_request_error, o 404, not_found_error, señala una solicitud mal formada: un parámetro inválido, un contenido incorrecto, o un identificador de modelo que ya no existe tal cual. Reintentar esa llamada sin corregirla reproduce el mismo error indefinidamente, la única salida es ajustar la llamada a la especificación vigente. Un identificador de modelo que ha cambiado de nombre desde que se escribió un script explica buena parte de estos errores 400 y 404: la documentación actual del modelo vigente sigue siendo lo primero que hay que abrir antes de sospechar otra cosa. Sin embargo, un 400 no siempre es una solicitud mal formada: la API también devuelve este código cuando el uso alcanza un límite de gasto fijado para la organización o el espacio de trabajo, salvo en el espacio de trabajo de Claude Code, que en ese caso puede devolver un 429 en su lugar. En este caso concreto, corregir la solicitud no sirve de nada, es el límite mismo lo que hay que elevar.

No todos los errores 429 se resuelven esperando

Un error 429, rate_limit_error, señala que se ha alcanzado un límite, pero dos límites distintos producen este mismo código. Una tasa temporal superada lleva una cabecera Retry-After y se resuelve respetando el plazo que indica antes de reintentar. Un límite de gasto alcanzado para un nivel, en cambio, no lleva ninguna cabecera Retry-After: la documentación lo dice sin rodeos, un 429 de este tipo falla sin descanso hasta que se restablezca el acceso. Esperar ante una respuesta así no sirve de nada: seguir reintentando en ese caso desperdicia llamadas en vano y retrasa la verdadera solución, elevar el límite fijado por la organización antes de reanudar el envío de solicitudes.

HTTP/1.1 429 Too Many Requests
retry-after: 12

{"type":"error","error":{"type":"rate_limit_error"}}

La presencia o ausencia de esta cabecera, no el simple código 429, es lo que decide entre esperar o actuar de otra manera.

En Claude Code, dos variables gobiernan los reintentos

Un error 529, overloaded_error, muestra en Claude Code un mensaje que señala que la API está a plena capacidad, sin consumir la cuota de uso de la sesión. Esta precisión importa: una serie de 529 puede preocupar sin por ello mermar el volumen de uso que autoriza la suscripción. Claude Code reintenta automáticamente los errores 429 y 529 de tipo tasa temporal, nunca los 429 de límite de gasto de una pasarela. CLAUDE_CODE_MAX_RETRIES limita el número de intentos, CLAUDE_CODE_RETRY_WATCHDOG permite reintentar indefinidamente en una sesión sin supervisión: la figura que acompaña esta lección da los valores exactos.

Decidir si hay que esperar o actuar ya aparece en un comando bloqueado, donde se plantea la misma disyuntiva frente a un silencio que puede anunciar un bloqueo real o un trabajo todavía en curso.