claude-code - 💡(How to fix) Fix [Feature Request] Graceful model fallback on overloaded_error — stop stalling sessions during peak load [1 comments, 2 participants]

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 to fallbackAfterRetries times
• If still overloaded, switch to fallbackModel for 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 /model switching 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

• /fast mode — 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