[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 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

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗