Índice
¿Alguna vez te ha frenado a mitad de una tarea en Claude Code un error como este?
API Error: 529 {"type":"error","error":
{"type":"overloaded_error","message":"Overloaded"}}
# o
API Error: 500 Internal server error.529 Overloaded significa que la API de Anthropic está temporalmente sobrecargada (saturada), y 500 significa que ha ocurrido un error inesperado dentro del servidor. Ambos son del lado del servidor y, lo más importante, no son un fallo en tu solicitud ni en tu configuración, ni que se haya agotado tu uso. La documentación oficial lo dice con claridad: "un 529 no es tu límite de uso y no cuenta contra tu cuota". En otras palabras, son el tipo de error que normalmente se resuelve con "espera un momento y reintenta".
Los puntos clave, de entrada. (1) 529/500 son del lado del servidor: no es culpa tuya (y no consumen tu cuota). (2) Claude Code ya reintenta automáticamente hasta 10 veces con retroceso exponencial antes de mostrarte nada: cuando aparece el mensaje amistoso, esos reintentos ya se han agotado. (3) La solución es "consultar la página de estado → esperar → cambiar de modelo con /model". La capacidad se gestiona por modelo, así que incluso cuando Opus está saturado, Sonnet a menudo pasa.
Esto es del lado del servidor, no es culpa tuya
— Claude Code ya está reintentando antes de mostrarte nada
Por eso la solución es "esperar y reintentar / cambiar con /model / consultar status.claude.com".
Básicamente no hay código ni configuración que arreglar.
1. Qué te está diciendo este error
HTTP 529 (overloaded_error / mensaje "Overloaded") es señal de que la API de Anthropic está temporalmente sobre su capacidad. La descripción oficial es literalmente que "la API está temporalmente sobrecargada" y que "puede ocurrir cuando las API experimentan mucho tráfico entre todos los usuarios". Significa que no es culpa de ninguna persona en concreto, sino que la demanda global superó brevemente la oferta.
HTTP 500 (api_error) es un error interno inesperado del lado de Anthropic. La documentación dice que "no está causado por tu prompt, tu configuración ni tu cuenta". Relacionado está el 504 (timeout_error), cuando una solicitud larga supera el tiempo de espera (ten en cuenta que Anthropic documenta el 504, mientras que 502/503 suelen provenir de la infraestructura intermedia, como las pasarelas).
El punto crucial: "529 y 500 son problemas del lado del servidor y no consumen tu cuota de uso". Son completamente distintos del usage limit reached de la cuota del plan y de tu propio límite de tasa 429 (los diferenciamos en el §4). Así que no hace falta ponerse en guardia para arreglar código o configuración: por defecto basta con "esperar y reintentar".
2. Claude Code ya está reintentando por ti
De hecho, antes de que veas siquiera el mensaje de error, Claude Code ya ha estado reintentando entre bastidores. Según la documentación oficial:
El comportamiento de reintento automático
Los errores de servidor, las respuestas de sobrecarga, los tiempos de espera de las solicitudes, las limitaciones temporales 429 y las conexiones caídas se reintentan, todos, hasta 10 veces con retroceso exponencial. Mientras reintenta, el indicador muestra una cuenta atrás Retrying in Ns · attempt x/y. Cuando aparece la cadena amistosa API Error:, esos 10 reintentos ya se han agotado.
Así que "apareció un 529 fugaz pero siguió adelante" es lo normal: el reintento automático lo absorbió. Por el contrario, si llegas al mensaje amistoso ("Repeated 529 Overloaded errors … try again in a moment. If it persists, check https://status.claude.com"), es señal de que la carga es lo bastante grave como para que ni siquiera los reintentos se recuperaran. Puedes ajustar los reintentos con CLAUDE_CODE_MAX_RETRIES (por defecto 10) y el tope por solicitud con API_TIMEOUT_MS (por defecto 600000 ms = 10 minutos): baja el número para fallar rápido en scripts, súbelo para aguantar durante un incidente más largo.
3. Qué puedes hacer tú
Los pasos ante un 529/500 son en realidad muy simples. Pruébalos en orden.
Espera, cambia, comprueba
/feedback (incluye el request_id para agilizar la investigación).
¿Dudas? 1) espera → 2) cambia con /model → 3) consulta el estado.
Mover el trabajo a horas de menor demanda también ayuda. Básicamente no hay configuración que arreglar.
Nota: el mensaje "Server is temporarily limiting requests" también se describe oficialmente como "una limitación efímera del lado del servidor, sin relación con tu límite de uso." También se resuelve con una breve espera, y es algo distinto del usage limit de la cuota del plan.
4. Cómo distinguirlo de errores parecidos
La familia de los "se detuvo" puede tener causas opuestas. Primero divide según "¿del lado del servidor o del tuyo?"
| Error | De quién es el problema | ¿Usa cuota? | Solución principal |
|---|---|---|---|
| 529 Overloaded | Del servidor (capacidad, afecta a todos) | No | Esperar y reintentar, /model, consultar estado |
| 500 / 504 | Del servidor (error interno / timeout) | No | Reintentar; si persiste, /feedback |
| 429 Rate limit | Tuyo (límite de tasa de tu clave API) | Sí (tu tasa) | Reduce el ritmo, sube de tier, espera el retry-after |
| usage limit reached | Tuyo (asignación del plan Pro/Max) | Sí (plan) | Esperar al reinicio; soluciones |
| 400 Invalid request | Tuyo (una solicitud mal formada) | No | Corregir el cuerpo de la solicitud |
Una regla mnemotécnica: 5xx (incluido el 529) es del lado del servidor = se resuelve si esperas. 429 y usage limit van de tu "cantidad" = ajusta la tasa o el plan. 400 va de tu "contenido" = corrige la solicitud. 429 y 529 son especialmente fáciles de confundir, pero 429 trae una cabecera retry-after y consume cuota, mientras que 529 no trae cabecera y no consume cuota: cosas distintas. Para otros errores comunes de Claude Code, consulta el resumen de errores.
5. Para desarrolladores (API/SDK)
Si ejecutas tu propia app sobre la API/SDK, el diseño correcto trata 529/500 como "un evento transitorio que normalmente puede ocurrir".
(1) Los SDK oficiales lanzan excepciones tipadas (OverloadedError, InternalServerError, etc.) y reintentan automáticamente los errores transitorios con retroceso exponencial: captura las clases de excepción, no coincidencias de cadenas. (2) Si reintentas tú mismo, usa "retroceso exponencial + jitter". (3) La cabecera retry-after está presente en el 429 pero NO en el 529, así que en un 529 espera con tu propio retroceso, no con tiempos guiados por la cabecera. (4) Ten un modelo de respaldo (Claude Code tiene --fallback-model). (5) Aumenta el tráfico de forma gradual para evitar el "límite de aceleración" del 429 tras un pico de uso. Si necesitas disponibilidad estable, Priority Tier y la Message Batches API también son opciones. Para lo básico, consulta Qué es una API de IA.
6. ¿Pico transitorio o un incidente?
El mismo 529/500 significa cosas distintas según sea "un pico que desaparece al instante" o "una caída continua que se repite".
Un pico transitorio (uno o unos pocos que se resuelven al reintentar) está dentro del rango normal de fluctuación de la demanda. El reintento automático suele absorberlo, y no hay nada que arreglar de tu lado. Por otro lado, "Repeated 529", o un 500 que sobrevive a los reintentos, es señal para sospechar de un incidente activo: comprueba primero status.claude.com y, si hay una caída publicada, esperar a que se recupere es lo único correcto. Si un 500 persiste sin incidente publicado, repórtalo con /feedback e incluye el request_id. En cualquier caso, todo lo que un usuario puede hacer ante un 529/500 es "reintentar, cambiar con /model, consultar el estado y reportar", y eso es genuinamente suficiente.
Resumen
Los mensajes de Claude Code "API Error: 529 Overloaded" y "500 Internal server error" son eventos del lado del servidor en los que la API de Anthropic está temporalmente sobrecargada o ha sufrido un error interno. No son un fallo en tu solicitud ni en tu configuración, ni que se haya agotado tu uso, y no consumen cuota. Claude Code reintenta automáticamente hasta 10 veces con retroceso exponencial antes de mostrarte nada; el mensaje amistoso significa que esos reintentos se han agotado.
La solución es simple: (1) espera y reintenta -> (2) cambia de modelo con /model (la capacidad es por modelo) -> (3) consulta status.claude.com -> (4) /feedback si un 500 persiste. Son distintos de 429 (tu tasa) y del usage limit (tu plan), y el 529 no trae retry-after. Los desarrolladores deberían diseñar en torno a ello con el reintento automático del SDK, retroceso exponencial + jitter y un modelo de respaldo. Si se repite, sospecha de un incidente y consulta la página de estado: en cualquier caso, básicamente no hay código ni configuración que arreglar. Relacionado: soluciones al usage limit, comparativa Opus/Sonnet/Haiku, resumen de errores de Claude Code.
Preguntas frecuentes
Q. ¿"529 Overloaded" lo causa algo que hice mal o mi código?
A. No, es un problema del lado del servidor. Un 529 significa que la API de Anthropic está temporalmente sobre su capacidad (congestión entre todos los usuarios); tu solicitud, tu configuración y tu cuenta no tienen nada que ver. La documentación lo dice con claridad: "un 529 no es tu límite de uso y no cuenta contra tu cuota." Normalmente se resuelve si esperas un momento y reintentas.
Q. Me dice una y otra vez que reintente, ¿debería machacarlo yo mismo?
A. En general, no. Claude Code ya reintenta automáticamente hasta 10 veces con retroceso exponencial antes de mostrar el error (Retrying in Ns · attempt x/y). El mensaje amistoso apareció porque esos 10 reintentos se agotaron. Espera un poco y, con un prompt largo, basta con escribir "inténtalo de nuevo" para volver a ejecutarlo con el contexto original. Puedes ajustar el número con CLAUDE_CODE_MAX_RETRIES.
Q. ¿Cuál es la diferencia entre 529 y 429?
A. 529 es sobrecarga del lado del servidor (afecta a todos; no consume cuota tuya), mientras que 429 es tu propio límite de tasa (superaste el RPM, etc. de tu clave API: va de tu asignación de tasa). Una pista: el 429 trae una cabecera retry-after, y el 529 no. Un 429 necesita ajuste de tu lado (reduce el ritmo, sube de tier); un 529 solo necesita esperar y reintentar o un cambio con /model.
Q. ¿Por qué a veces funciona cambiar con /model?
A. Porque la capacidad (congestión) se gestiona por modelo. Aunque Opus esté con mucha carga, Sonnet puede pasar al instante si tiene margen. El propio Claude Code a veces sugiere un cambio cuando hay carga ("Opus is experiencing high load, please use /model to switch to Sonnet"). Cuando tienes prisa, cambiar a un modelo más ligero o distinto con /model es un atajo rápido.
Q. Recibo 529/500 sin parar. ¿Qué debería hacer?
A. Sospecha de un incidente activo y consulta status.claude.com. Si hay una caída publicada, lo único que puedes hacer es esperar a que se recupere. Si un 500 persiste sin incidente publicado, repórtalo con /feedback incluyendo el request_id para que Anthropic pueda investigar. Como 529/500 son eventos del lado del servidor, básicamente no hay código ni configuración que tengas que arreglar.
