Error 529 en Claude Code: qué hacer cuando la API se sobrecarga

El error 529 significa que el modelo que estás usando no tiene capacidad libre en ese momento para nadie, no que hayas agotado tu plan. Cuando el mensaje llega a tu pantalla, Claude Code ya ha reintentado la petición hasta 10 veces con esperas crecientes, así que reenviar al instante suele repetir lo mismo. Tienes tres salidas: cambiar de modelo con /model para seguir ahora, esperar unos minutos vigilando la página de estado que nombra el propio mensaje, o dejar configurado un modelo de respaldo (fallbackModel) para que la próxima sobrecarga no te pare. En CI y scripts, CLAUDE_CODE_RETRY_WATCHDOG=1 hace que Claude Code espere en vez de fallar.

Este es el mensaje completo cuando usas la API de Anthropic, según la documentación de errores de Claude Code:

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

La última frase cambia según tu ruta: con Amazon Bedrock, Google Cloud Agent Platform o Microsoft Foundry nombra la página de estado de ese proveedor, y si Claude Code apunta a una pasarela con ANTHROPIC_BASE_URL, nombra el host de esa pasarela.

Qué ha pasado antes de que veas el mensaje

La API de Anthropic define el 529 como overloaded_error: la API está sobrecargada de forma temporal por un tráfico alto de todos los usuarios (errores de la API). Es capacidad compartida, no un límite tuyo. La documentación de Claude Code lo dice sin rodeos: un 529 no es tu límite de uso y no cuenta contra tu cuota.

Mientras tanto, Claude Code ha estado trabajando por ti. Ante respuestas de sobrecarga, errores de servidor y tiempos de espera que llegan antes de que empiece la respuesta, reintenta hasta 10 veces con retroceso exponencial. En el indicador de progreso verás algo como Retrying in Ns · attempt x/y; desde la versión 2.1.198, a partir del tercer intento la etiqueta dice el motivo concreto y, si es un 529, la línea de debajo indica dónde mirar el estado del servicio.

De ahí salen dos consecuencias prácticas:

• Cuando aparece el error final, los reintentos rápidos ya se han agotado. Pulsar Intro otra vez un segundo después no cambia nada que no hayan probado ya diez intentos.
• Tu mensaje sigue en la conversación. Cuando vuelvas a intentarlo, basta con escribir try again o «vuelve a intentarlo», sin pegar otra vez un prompt largo.

Decide en un minuto: esperar, cambiar de modelo o automatizarlo

La pieza que más cambia la decisión es que la capacidad se mide por modelo. Si Opus está saturado, otro modelo puede tener hueco en ese mismo momento. Por eso Claude Code a veces te lo propone directamente:

Opus is experiencing high load, please use /model to switch to Sonnet

En la app de escritorio (pestaña Code o Cowork) el aviso es Opus is experiencing high load. Switch to Sonnet. y el cambio se hace desde el selector de modelo de la app.

Ningún dato público dice qué modelo estará menos cargado en un momento dado, y tampoco existe un tiempo de recuperación garantizado. El mensaje oficial se limita a «normalmente es temporal». Lo que sí es fiable es el mecanismo: cambiar de modelo te saca de la cola saturada de ese modelo concreto.

Sobre el coste: lo que responda el otro modelo se cuenta como trabajo de ese modelo en tu ruta. Con API key se paga a su tarifa por tokens; con suscripción, consume de tu plan igual que cualquier respuesta suya. Si el modelo de respaldo es de gama superior al principal, revisa antes su precio en tu consola.

Configura un modelo de respaldo para la próxima vez

Claude Code puede cambiar solo a otro modelo cuando el principal está sobrecargado, no disponible o devuelve otro error de servidor que no se resuelve reintentando. Lo describe la sección de cadenas de modelos de respaldo de la documentación.

Para una sola sesión, usa la opción de línea de comandos con una lista separada por comas:

claude --fallback-model sonnet,haiku

Para que quede fijo en todas tus sesiones, añade fallbackModel como lista en tu archivo de ajustes (por ejemplo, ~/.claude/settings.json para tu usuario o .claude/settings.json en el proyecto):

{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

Cada entrada admite el nombre completo del modelo o un alias como sonnet, y "default" equivale a tu modelo por defecto. Si usas Bedrock, Agent Platform o Foundry, esos despliegues trabajan con identificadores de modelo propios del proveedor, así que escribe los que tengas disponibles en tu cuenta.

Antes de fiarte de la cadena, conviene conocer sus límites:

• Solo dura el turno actual. Tu siguiente mensaje vuelve a probar primero el modelo principal. No te quedas en el de respaldo sin darte cuenta.
• Máximo tres modelos. Tras quitar duplicados, Claude Code ignora las entradas sobrantes y prueba el resto en orden.
• No salta con cualquier error. Autenticación, facturación, límites de uso (429), peticiones demasiado grandes, errores de red y bloqueos por la política de tu organización nunca activan el cambio. Si tu problema es un 429, la cadena no te ayudará.
• No verás confirmación. Claude Code no la muestra al arrancar y /status tampoco la enseña. La primera señal de que funciona es el aviso que aparece cuando se produce un cambio.
• Respeta las restricciones. Si tu organización limita modelos con availableModels, las entradas fuera de esa lista se descartan. Durante la compactación del contexto no cambia a un modelo con ventana de contexto más pequeña que la del principal.
• También cubre subagentes desde la versión 2.1.247: el subagente sigue con el modelo de respaldo que acepte la petición, y tu sesión mantiene su modelo.

La opción --fallback-model tiene prioridad sobre el ajuste fallbackModel, así que puedes tener una cadena fija y sustituirla en una sesión concreta.

En CI y scripts: que Claude Code espere en vez de fallar

En una ejecución sin nadie delante, fallar tras diez reintentos suele ser peor que esperar. Para eso existe una variable de entorno descrita en la sección de reintentos:

export CLAUDE_CODE_RETRY_WATCHDOG=1
claude -p "ejecuta los tests y corrige los que fallen" --fallback-model sonnet

Con CLAUDE_CODE_RETRY_WATCHDOG=1:

• los errores de capacidad 429 y 529 se reintentan sin límite en lugar de rendirse al agotar los reintentos;
• desde la versión 2.1.239, un 429 que indica límite de gasto o créditos agotados sigue fallando al momento, porque esperar no lo arregla;
• desde la versión 2.1.199, el resto de errores transitorios (errores de servidor, tiempos de espera, conexiones caídas) pasan a 300 reintentos por defecto, unas tres horas de espera acumulada.

Como la espera puede ser larga, pon un tiempo máximo al job en tu sistema de CI (en GitHub Actions, timeout-minutes) para que un incidente prolongado no te ocupe runners durante horas.

Si prefieres lo contrario, que un script falle pronto y lo gestione tu propia lógica, baja CLAUDE_CODE_MAX_RETRIES. Su valor por defecto es 10 y, sin el watchdog, el máximo es 15.

Un detalle de ruta en CI: en modo no interactivo (-p), si ANTHROPIC_API_KEY está definida, Claude Code siempre la usa. Tu job va entonces por la API de Anthropic con esa clave, aunque en tu máquina uses suscripción.

Qué página de estado te corresponde

El mensaje de error ya te dice dónde mirar, porque su última frase se adapta a tu configuración. Si no lo tienes delante, /status muestra qué credencial está activa.

Si crees que usas tu suscripción pero tienes ANTHROPIC_API_KEY definida en el terminal, Claude Code puede estar usando esa clave. En modo interactivo te pide aprobación la primera vez; unset ANTHROPIC_API_KEY te devuelve a la suscripción. No provoca un 529 por sí misma, pero cambia qué ruta estás usando.

Con una pasarela conviene tener clara una cosa: reenvía tus peticiones, pero no añade capacidad a los modelos de Anthropic. Si el 529 llega desde arriba, lo verás igual.

Al leer status.claude.com, fíjate en el título de los incidentes. La página lista componentes como Claude API o Claude Code, pero no uno por modelo; los incidentes, en cambio, suelen nombrar el modelo afectado. Entre el 2 y el 3 de septiembre de 2026 hubo uno de errores elevados en Claude Sonnet 5, el 15 de septiembre otro de picos de errores en Claude Mythos 5.1 y Claude Fable 5.1, y el 22 de septiembre uno que afectaba a varios modelos. A 28 de septiembre de 2026, la página marcaba todos los sistemas operativos. Si el incidente abierto nombra tu modelo, cambiar de modelo es la salida lógica.

Un estado en verde no significa que tu 529 sea imaginario: la página publica incidentes, no la carga de cada modelo minuto a minuto. Tampoco significa que haya una caída. Con el estado en verde y un 529 aislado, lo razonable es cambiar de modelo o esperar un poco, sin hablar de caída ni tocar tu configuración.

Cuando lo que ves no es un 529

Otros mensajes se parecen en lo que sientes («Claude Code no me deja seguir»), pero piden pasos distintos:

El corte a mitad de respuesta merece atención propia. Desde la versión 2.1.199, si la sobrecarga llega después de que Claude haya terminado un bloque de texto o una llamada a herramienta, Claude Code conserva lo completado, ejecuta las llamadas a herramientas terminadas y continúa desde ahí. No reenvía la petición entera porque eso podría ejecutar dos veces las mismas herramientas. Antes de repetir nada, revisa qué quedó hecho de verdad; en Claude Code API Error 500 y 529: reanuda sin duplicar trabajo tienes cómo reanudar la sesión y comprobar efectos secundarios.

Si el 529 no te sale en Claude Code sino en tu propio código con el SDK, el manejo es otro: los SDK oficiales reintentan dos veces por defecto y lo ajustas tú con max_retries. Lo tienes en Claude API 529 overloaded_error: recupéralo sin tratarlo como un 429. Un matiz de la misma documentación: si tu organización dispara su uso de golpe, puedes recibir un 429 por límites de aceleración en lugar de un 529, y la solución es subir el tráfico de forma gradual.

Cuándo dejar de esperar y reportarlo

Tiene sentido reportarlo cuando el 529 se repite durante un buen rato, cambiar de modelo tampoco funciona y la página de estado de tu ruta no muestra ningún incidente. Entonces:

1. Ejecuta /feedback dentro de Claude Code. Envía la transcripción y tu descripción a Anthropic y ofrece abrir una incidencia en GitHub ya rellenada. En Bedrock, Agent Platform, Foundry u otros proveedores externos, guarda un archivo local que puedes mandar a tu representante de cuenta de Anthropic.
2. Ejecuta claude doctor en tu terminal (o /doctor dentro de Claude Code) para descartar un problema de instalación.
3. Busca en las incidencias de GitHub de Claude Code si alguien ya ha reportado lo mismo con tu versión.
4. Si usas una pasarela, repórtalo primero a su soporte: el mensaje te ha dicho que el 529 viene de ese host.

Adjunta lo que permite reproducir el caso sin preguntas de ida y vuelta:

• el mensaje de error exacto, incluido el host o la página de estado que nombra;
• el modelo que usabas y si con otro modelo funcionó;
• la ruta activa según /status (suscripción, API key, proveedor cloud o pasarela);
• la hora aproximada con tu zona horaria y cuánto tiempo lleva pasando;
• tu versión (claude --version) y si tienes configurada una cadena de respaldo o el watchdog.