Tu plan B para el error 529 en Claude Code

Cuando tu modelo devuelve un 529 (Overloaded) a mitad de tarea, la petición no tiene por qué morir. Configura una cadena de modelos de respaldo y Claude Code degrada solo en vez de dejarte tirado.

Cadena de fallback en Claude Code: el modelo principal devuelve un 529 y la petición salta al siguiente modelo de respaldo

TL;DR Estás a mitad de una tarea larga y tu modelo devuelve Overloaded (error 529). En vez de fallar la petición, Claude Code puede saltar solo a un modelo de respaldo y seguir. Le configuras una cadena de hasta tres modelos con --fallback-model o con fallbackModel en settings, y cuando el principal está saturado o caído, degrada en orden en lugar de tumbarte la sesión.

Degradar en vez de morir

Cuando tu modelo principal está saturado (529), no disponible, o devuelve otro error de servidor no reintentable, Claude Code cambia a un modelo de respaldo y sigue, avisándote del cambio. Los errores de autenticación, facturación, rate-limit, tamaño de petición o transporte no disparan el salto: siguen su reintento y manejo normal. Y el cambio dura solo el turno actual: tu siguiente mensaje vuelve a probar el principal primero.

Cómo se ve

✳ claude-opus-4-8 · Overloaded (HTTP 529)
  ↳ fallback → claude-sonnet-5
✔ la tarea sigue sin que pierdas el turno

Setup

1. Una sesión: el flag

claude --fallback-model sonnet,haiku

Lista separada por comas, probada en orden. El flag manda sobre el setting.

2. Persistente: settings.json

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

Un array. Cada eslabón acepta un nombre de modelo o un alias, y "default" expande al modelo por defecto.

3. Qué dispara el salto (y qué no)

Sí: principal saturado (529), no disponible, u otro error de servidor no reintentable.
No: auth, facturación, rate-limit, tamaño de petición, transporte. Esos reintentan o fallan como siempre.

4. Los límites de la cadena

Tope de tres modelos, tras quitar duplicados; los extra se ignoran.
Un eslabón se salta si el modelo no está disponible (p.ej. uno retirado que dejaste fijado) o si está fuera de tu availableModels (ahí se descarta al leer la cadena, ni se intenta).

Referencia

Elemento	Qué es
`--fallback-model a,b`	Cadena para una sesión (el flag manda sobre el setting)
`"fallbackModel": [...]`	Cadena persistente en `settings.json` (array)
`"default"`	Expande al modelo por defecto
Tope de la cadena	3 modelos (se quitan duplicados; extra ignorados)
Dispara el salto	529 / no disponible / error de servidor no reintentable
No lo dispara	auth, facturación, rate-limit, tamaño, transporte
Alcance	Solo el turno actual; el siguiente vuelve al principal

Ojo con no confundirla: esta es la fallback por disponibilidad. Es distinta de la automatic model fallback por contenido, donde Fable 5 reencamina a Opus las peticiones que marcan sus clasificadores de ciberseguridad o biología. Una es "mi modelo está caído"; la otra, "este contenido se reencamina". Y si lo que quieres no es sobrevivir a una caída sino elegir bien el modelo de entrada, ese es otro tip: este cubre el plan B para cuando tu elección no está disponible.

Documentación oficial: Model configuration — Fallback model chains