Setting up fallback models so Claude Code doesn't stall on overload

You are in the middle of work, you type a prompt, and Claude Code answers with overloaded. The model is saturated right now, too many people at once, and your turn breaks off. With Opus this happens more often than with the smaller models, because Opus is the most expensive and most in-demand tier. Anthropic recently doubled the rate limits for Claude Code, which helps, but the problem is not gone.

Instead of switching models by hand every time, you can tell Claude Code to move to the next model automatically when one is saturated. Since version 2.1.166 there is the fallbackModel setting for that, with which you build a chain of up to three models. If the first drops out, the second comes, then the third. In the best case you do not even notice anything happened, except that the answer comes from a different model. I will show in ten steps how to set that up, and just as importantly, what the chain does not catch.

1. Understand when the fallback actually kicks in

The fallback is built for one specific case: the primary model is overloaded or currently unavailable. That is the overloaded error. Exactly then Claude Code tries the next model in your chain.

It is not a cure-all for every error. That is the most important thing to understand right at the start, otherwise you will be puzzled later. I get to the exceptions in step 7.

2. Check the version

The chain of several fallback models exists from 2.1.166. Check briefly:

claude --version

Older? Then update first, see Claude Code update strategy. The update is genuinely worth it here, because before 2.1.166 there was only a single fallback, and it did not apply in interactive sessions.

3. Think through a sensible chain

Before you write anything into a file, think about the order. The logic is simple: at the top the model you actually want, below it fallback options that are still good enough and less often saturated.

A typical chain for someone who normally works on Opus looks like this: Opus first, then Sonnet, then Haiku. Opus is the strongest tier and most often overloaded, Sonnet is the solid middle ground, Haiku is the budget tier that is almost always available. That way, in an emergency, you fall to a weaker model rather than getting no answer at all. If you want the differences between the tiers laid out cleanly again, see level 1 lesson Comparing models.

4. Enter the setting

The fallbackModel setting goes into your settings.json. Globally that lives at ~/.claude/settings.json, per project at .claude/settings.json in the repo. You enter up to three models, which are tried in that order.

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

Take the exact model identifier from the current docs, the strings change with every model generation. If you are unsure which name currently applies, check the changelog or the settings docs, both linked below.

5. Set the fallback for individual sessions too

You do not have to write it permanently into your settings. For a single run there is the flag:

claude --fallback-model sonnet

Since 2.1.166 this flag also works in interactive sessions, no longer only in headless mode. That is handy when you want a fallback just for today without touching your global config.

6. Test without waiting for the next overload

You do not want to find out your chain is wrong only during the next real overload. The pragmatic test: briefly set a model name that does not exist as your primary, or a model you have no access to, and see whether Claude Code jumps cleanly to the first fallback. If that works, you know the chain holds. Then put the correct primary model back.

7. What the chain does not catch

Here is where most people have wrong expectations. The fallback kicks in on overloaded and on unavailable. It does not kick in on these errors:

Auth errors, so an expired token or missing permission. Rate limit errors, when you have blown your own quota. Request size errors, when your prompt or context is simply too large. And transport errors, so network problems. These four reach you immediately, without a detour via another model, because another model would reject them just the same. Claude Code does retry a turn once on the fallback model for an unexpected, non-repeatable API error, but the four error types named above come straight through.

That is a good thing. It would be nonsense to try three models on an expired token. But you have to know it, otherwise you look for the fault in the wrong place.

8. Combine it with cost control

A fallback to a cheaper model is incidentally also a cost lever. When your chain falls from Opus to Sonnet, the turn gets cheaper, not more expensive. But be careful in the other direction: a chain that points downwards is good, one that accidentally has a more expensive model as its fallback costs you more in the overload case. So always build the chain descending.

If you want your spending under control in general, combine this with the playbook Cost controls for the daily driver. Fallback and budget limits work well together.

9. Keep the model names current

This is the trap that catches you a few months from now. Model names go stale. When a new generation arrives and the old one is retired, your chain suddenly points at a model that no longer exists, and the fallback runs into the void. Put it on your radar: with every major model migration, go through the fallbackModel entries too. What such a migration looks like is in the playbook Opus 5 migration.

10. Stay realistic about when it pays off

If you work a lot on Opus and regularly see overloaded, the chain is a clear win, you stop losing turns. If you are mostly on Sonnet or Haiku anyway, which are rarely saturated, you barely need it. And if your aborts were really auth or network problems, the fallback does not help you at all, in that case you belong in the playbook Claude Code acting up after a config change and should look at step 9 there.

What next

If you are in the middle of making your setup more robust, the companion playbook Claude Code acting up after a config change is the next logical step, because not every abort is an overload. For the bigger picture on models and cost, level 1 lesson Comparing models is worth it.

Source

• Claude Code changelog, version 2.1.166 (fallbackModel, --fallback-model in interactive sessions, error behaviour on auth/rate-limit/request-size/transport): https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
• Claude Code settings docs: https://code.claude.com/docs/en/settings