[Feature Request] Graceful model fallback on overloaded_error — stop stalling sessions during peak load
Resolved 💬 3 comments Opened Apr 16, 2026 by n0t-4m17h Closed Apr 19, 2026
Problem
When the Anthropic API returns overloaded_error, Claude Code retries the same model with backoff (up to 10 attempts). During peak load this can stall a session for several minutes with no progress, even though other models (e.g. Sonnet/Haiku) may have capacity.
Example output seen during a session:
{"type":"error","error":{"type":"overloaded_error","message":"Overloaded"},"request_id":"req_011Ca71E6bFqZYFY6SF15Boz"}
Retrying in 33 seconds… (attempt 8/10)
This is particularly painful on Opus, which appears more sensitive to overload events than Sonnet/Haiku.
Proposal
Add an opt-in settings.json flag that falls back to a configured alternate model after N overload retries. For example:
{
"model": "claude-opus-4-6",
"fallbackModel": "claude-sonnet-4-6",
"fallbackAfterRetries": 2
}
Behaviour:
- On
overloaded_error, retry the primary model up tofallbackAfterRetriestimes - If still overloaded, switch to
fallbackModelfor the remainder of the current turn (or session, configurable) - Surface a clear one-line notice to the user when the fallback triggers
Why
- Opus is disproportionately affected by overload during peak hours
- Manual
/modelswitching requires the user to be watching the terminal, which defeats long-running or background work - A Sonnet response now is almost always more useful than an Opus response in five minutes
- Hooks currently have no event for API errors, so this cannot be scripted by users
Alternatives considered
/fastmode — helps sometimes but still same model, still overloadable- Manual
/model— works but requires active attention - A hook event for API errors — more flexible but also more work for users; a built-in flag covers the common case
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗