TL;DR You're deep in a long task and your model returns
Overloaded(error 529). Instead of failing the request, Claude Code can switch to a backup model on its own and keep going. You give it a chain of up to three models with--fallback-modelor withfallbackModelin settings, and when the primary is overloaded or down, it degrades in order instead of killing your session.
Degrade instead of dying
When your primary model is overloaded (529), unavailable, or returns another non-retryable server error, Claude Code switches to a backup model and carries on, showing you a notice. Authentication, billing, rate-limit, request-size, and transport errors don't trigger the switch: those follow their normal retry and error handling. And the switch lasts for the current turn only: your next message tries the primary first again.
What it looks like
✳ claude-opus-4-8 · Overloaded (HTTP 529)
↳ fallback → claude-sonnet-5
✔ the task keeps going, you don't lose the turn
Setup
1. One session: the flag
claude --fallback-model sonnet,haiku
A comma-separated list, tried in order. The flag takes precedence over the setting.
2. Persistent: settings.json
{
"fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}
An array. Each element takes a model name or an alias, and "default" expands to the default model.
3. What triggers the switch (and what doesn't)
- Yes: primary overloaded (529), unavailable, or another non-retryable server error.
- No: auth, billing, rate-limit, request-size, transport. Those retry or fail as usual.
4. The chain's limits
- Capped at three models, after duplicates are removed; extras are ignored.
- An element is skipped if the model is unavailable (e.g. a retired one you left pinned) or if it's outside your
availableModels(there it's dropped when the chain is read, never even tried).
Reference
| Element | What it is |
|---|---|
--fallback-model a,b |
Chain for one session (the flag beats the setting) |
"fallbackModel": [...] |
Persistent chain in settings.json (array) |
"default" |
Expands to the default model |
| Chain cap | 3 models (duplicates removed; extras ignored) |
| Triggers the switch | 529 / unavailable / non-retryable server error |
| Doesn't trigger it | auth, billing, rate-limit, request size, transport |
| Scope | Current turn only; the next one goes back to the primary |
Don't mix it up: this is the availability fallback. It's different from the content-based automatic model fallback, where Fable 5 reroutes to Opus the requests its cybersecurity or biology classifiers flag. One is "my model is down"; the other is "this content gets rerouted". And if what you want isn't surviving an outage but picking the right model up front, that's a different tip: this one covers the plan B for when your pick isn't available.
Official docs: Model configuration — Fallback model chains