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

> Cuando ves el 529, Claude Code ya ha reintentado hasta 10 veces y no te ha gastado cuota: cambia de modelo con /model, deja un fallbackModel o espera.

- URL: https://blog.laozhang.ai/es/posts/claude-code-overloaded-error
- Published: 2026-04-11
- Updated: 2026-09-28
- Author: LaoZhang AI Team (https://blog.laozhang.ai/es/about)
- Topic: Claude Code
- Tags: Claude Code, Error 529, Overloaded, fallbackModel, Anthropic, Solución de problemas

---
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](https://code.claude.com/docs/en/errors#api-error-repeated-529-overloaded-errors):

```text
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](https://platform.claude.com/docs/en/api/errors)). 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:

```text
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.

| Tu situación | Qué hacer |
| --- | --- |
| Estás en mitad de una tarea y necesitas seguir ya | `/model` y elige otro modelo (en escritorio, el selector de modelo). El nuevo modelo sigue la conversación donde estaba |
| La página de estado tiene un incidente que nombra tu modelo | Cambiar de modelo tiene sentido: el problema está acotado a ese modelo |
| El incidente habla de varios modelos o de todo el servicio | Cambiar ayuda poco; espera a que se resuelva |
| No tienes prisa y el estado está en verde | Espera unos minutos y vuelve a intentarlo en la misma conversación |
| Te pasa a menudo y no quieres ir cambiando a mano | Configura una cadena de respaldo (siguiente sección) |
| Es una ejecución desatendida: CI, scripts, agentes remotos | Activa `CLAUDE_CODE_RETRY_WATCHDOG` (más abajo) |

![Diagrama de decisión ante un 529: si necesitas seguir ya, cambia de modelo con /model; si no, según la página de estado cambia de modelo, espera o reintenta, y para errores frecuentes o CI usa fallbackModel o CLAUDE_CODE_RETRY_WATCHDOG=1](https://blog.laozhang.ai/posts/es/claude-code-overloaded-error/img/decidir-529.webp)

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](https://code.claude.com/docs/en/model-config#fallback-model-chains) de la documentación.

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

```bash
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):

```json
{
  "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](https://code.claude.com/docs/en/errors#tune-retry-behavior):

```bash
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.

| Cómo usas Claude Code | Dónde mirar |
| --- | --- |
| Suscripción Pro, Max, Team o Enterprise, o API key de Anthropic | [status.claude.com](https://status.claude.com) |
| Amazon Bedrock, Google Cloud Agent Platform o Microsoft Foundry | La página de estado de ese proveedor, que nombra el mensaje |
| Una pasarela propia o de terceros con `ANTHROPIC_BASE_URL` | El estado y el soporte de esa pasarela, cuyo host aparece en el mensaje |

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.

![Tres rutas de Claude Code y su página de estado: suscripción o API key en status.claude.com, proveedor cloud en su propia página y pasarela en su soporte, con el aviso de que una pasarela no añade capacidad](https://blog.laozhang.ai/posts/es/claude-code-overloaded-error/img/rutas-estado.webp)

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:

| Lo que aparece | Qué es | Adónde ir |
| --- | --- | --- |
| `API Error: Request rejected (429)` | Límite de peticiones de tu API key, de tu cuenta de Bedrock o de tu proyecto de Google Cloud. Ni cambiar de modelo por capacidad ni la cadena de respaldo lo resuelven. Revisa con `/status` que no se esté usando una `ANTHROPIC_API_KEY` de nivel bajo | [Claude Code: cómo resolver Rate limit reached y retomar la tarea](https://blog.laozhang.ai/es/posts/claude-code-rate-limit-reached) |
| `Server is temporarily limiting requests (not your usage limit)` | Un freno breve del servidor, no tu límite de uso | Nada: Claude Code lo reintenta solo |
| `API Error: 500 Internal server error` | Fallo interno de la API, no causado por tu prompt ni tu cuenta | [Claude Code API Error 500 y 529: reanuda sin duplicar trabajo](https://blog.laozhang.ai/es/posts/claude-code-500-529-rate-limit) |
| `API Error: Server error mid-response. The response above may be incomplete.` | Un 529 o 5xx llegó cuando Claude ya había completado parte de la respuesta | Sección siguiente |
| `Unable to connect to API` o errores `ECONNRESET` | Red, proxy o certificados de tu lado | [Claude Code Unable to connect to API: solución para ECONNREFUSED, ECONNRESET y proxy](https://blog.laozhang.ai/es/posts/claude-api-error-connection-error) |

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](https://blog.laozhang.ai/es/posts/claude-code-500-529-rate-limit) 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](https://blog.laozhang.ai/es/posts/claude-api-error-529-overloaded). 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.

## Fuentes

Páginas externas que cita esta guía, en el orden en que aparecen. Última actualización: 2026-09-28.

- [documentación de errores de Claude Code](https://code.claude.com/docs/en/errors) (code.claude.com)
- [errores de la API](https://platform.claude.com/docs/en/api/errors) (platform.claude.com)
- [cadenas de modelos de respaldo](https://code.claude.com/docs/en/model-config) (code.claude.com)
- [status.claude.com](https://status.claude.com/) (status.claude.com)