Configurar modelos de fallback para que Claude Code no se quede colgado en sobrecarga

Estás en plena faena, escribes un prompt, y Claude Code responde con overloaded. El modelo está saturado justo ahora, demasiada gente a la vez, y tu turno se corta. Con Opus pasa más que con los modelos pequeños, porque Opus es el nivel más caro y más demandado. Anthropic dobló hace poco los rate limits de Claude Code, lo que ayuda, pero el problema no desaparece con eso.

En vez de cambiar de modelo a mano cada vez, puedes decirle a Claude Code que pase automáticamente al siguiente cuando uno está saturado. Para eso existe desde la versión 2.1.166 el ajuste fallbackModel, con el que construyes una cadena de hasta tres modelos. Si el primero cae, entra el segundo, luego el tercero. En el mejor de los casos ni te enteras de que ha pasado algo, salvo porque la respuesta viene de otro modelo. Te enseño en diez pasos cómo montarlo, y algo igual de importante, qué cosas no atrapa la cadena.

1. Entender cuándo entra el fallback

El fallback está hecho para un caso muy concreto: el modelo primario está sobrecargado o no disponible en ese momento. Ese es el error overloaded. Justo entonces Claude Code prueba el siguiente modelo de tu cadena.

No es una panacea contra cualquier error. Eso es lo más importante que deberías entender desde el principio, si no te vas a extrañar después. Las excepciones las cuento en el paso 7.

2. Comprobar la versión

La cadena de varios modelos de fallback existe a partir de 2.1.166. Comprueba rápido:

claude --version

¿Más antigua? Entonces actualiza primero, mira Estrategia de actualización de Claude Code. Aquí la actualización merece de verdad la pena, porque antes de 2.1.166 solo había un fallback único, y no entraba en sesiones interactivas.

3. Pensar una cadena con sentido

Antes de escribir nada en un fichero, piensa el orden. La lógica es simple: arriba el modelo que realmente quieres, debajo alternativas que siguen siendo lo bastante buenas y se saturan menos.

Una cadena típica para quien trabaja normalmente sobre Opus es así: primero Opus, luego Sonnet, luego Haiku. Opus es el nivel más fuerte y el que más se sobrecarga, Sonnet es el término medio sólido, Haiku es el nivel económico que casi siempre está disponible. Así, en caso de apuro, caes a un modelo más flojo antes que quedarte sin respuesta. Quien quiera repasar las diferencias entre niveles, que mire la lección de nivel 1 Comparar modelos.

4. Meter el ajuste

El ajuste fallbackModel va en tu settings.json. En global está en ~/.claude/settings.json, por proyecto en .claude/settings.json dentro del repo. Metes hasta tres modelos, que se prueban en ese orden.

{
  "fallbackModel": ["sonnet", "haiku"]
}

El identificador exacto del modelo lo sacas de la documentación actual, esas cadenas cambian con cada generación de modelos. Si no tienes claro qué nombre vale ahora, mira el changelog o la documentación de settings, los dos están enlazados abajo.

5. Poner el fallback también para sesiones sueltas

No hace falta que lo dejes fijo en los settings. Para una tirada suelta está el flag:

claude --fallback-model sonnet

Desde 2.1.166 este flag también funciona en sesiones interactivas, ya no solo en modo headless. Va bien cuando quieres una alternativa solo por hoy, sin tocar tu configuración global.

6. Probarlo sin esperar a la próxima sobrecarga

No quieres descubrir que tu cadena está mal justo en la siguiente sobrecarga real. La prueba pragmática: pon un momento como modelo primario un nombre que no exista, o un modelo al que no tengas acceso, y mira si Claude Code salta limpio al primer fallback. Si eso va, sabes que la cadena entra. Después devuelves el modelo primario correcto.

7. Lo que la cadena no atrapa

Aquí es donde la mayoría tiene expectativas equivocadas. El fallback entra con overloaded y con no disponible. No entra con estos errores:

Errores de autenticación, o sea un token caducado o falta de permiso. Errores de rate limit, cuando has reventado tu propio cupo. Errores de tamaño de petición, cuando tu prompt o contexto es sencillamente demasiado grande. Y errores de transporte, o sea problemas de red. Esos cuatro te llegan de inmediato, sin rodeo por otro modelo, porque otro modelo los rechazaría igual. Claude Code sí reintenta una vez el turno en el modelo de fallback ante un error de API inesperado y no repetible, pero los cuatro tipos citados pasan directos.

Y está bien que así sea. Sería absurdo probar tres modelos con un token caducado. Pero tienes que saberlo, si no buscas el fallo donde no está.

8. Combinarlo con control de costes

Un fallback a un modelo más barato es de paso también una palanca de coste. Cuando tu cadena cae de Opus a Sonnet, el turno sale más barato, no más caro. Pero cuidado en el sentido contrario: una cadena que apunta hacia abajo es buena, una que por descuido tiene un modelo más caro como fallback te cuesta más en caso de sobrecarga. Así que construye la cadena siempre descendente.

Quien quiera tener el gasto bajo control en general, que lo combine con el playbook Controles de coste para el daily driver. Fallback y límites de presupuesto se llevan bien.

9. Mantener los nombres de modelo al día

Esta es la trampa que te pilla dentro de unos meses. Los nombres de modelo caducan. Cuando sale una generación nueva y se retira la vieja, tu cadena apunta de repente a un modelo que ya no existe, y el fallback se queda en el aire. Ponlo en tu radar: en cada migración grande de modelos, repasa también las entradas de fallbackModel. Cómo transcurre una migración así está en el playbook Migración a Opus 5.

10. Ser realista sobre cuándo compensa

Si trabajas mucho sobre Opus y ves overloaded con regularidad, la cadena es una ganancia clara, dejas de perder turnos. Si de todas formas andas casi siempre en Sonnet o Haiku, que rara vez se saturan, apenas lo necesitas. Y si tus cortes eran en realidad problemas de autenticación o de red, el fallback no te ayuda nada, entonces lo tuyo es más bien el playbook Claude Code falla tras un cambio de configuración, y ahí el paso 9.

Qué sigue

Si justo estás haciendo tu setup más robusto, el playbook compañero Claude Code falla tras un cambio de configuración es el siguiente paso lógico, porque no todo corte es una sobrecarga. Para el contexto más amplio de modelos y costes merece la pena la lección de nivel 1 Comparar modelos.

Source

• Changelog de Claude Code, versión 2.1.166 (fallbackModel, --fallback-model en sesiones interactivas, comportamiento ante errores de auth/rate-limit/tamaño/transporte): https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
• Documentación de settings de Claude Code: https://code.claude.com/docs/en/settings