›_ Claude Code Issues
Claude Code Issues / #48665

Proposal: Client-Side API Failover and High-Availability Routing

Status Fixed / completed
Maintainer reply None cached
Activity 5 comments · opened Apr 15, 2026 · closed Apr 15, 2026

Preflight Checklist

  • [x] I have searched existing requests and this feature hasn't been requested yet
  • [x] This is a single feature request (not multiple features)

Problem Statement

Problem Statement:
Claude Code is increasingly used as a primary driver for professional software engineering. However, it currently has a single point of failure: the primary API gateway. During major outages or capacity events (as seen in March 2026), the tool becomes unusable, causing total productivity loss. While internal retries exist, they cannot solve a
systemic provider outage.

Proposed Solution: An "Availability Suite"
I propose a first-class "Failover" mechanism that allows the CLI to transparently route requests to a secondary configuration (e.g., a different billing account or a provider like OpenRouter) upon encountering specific terminal errors (5xx, 429).

This feature would act as the logical connective tissue between several existing community requests:

  1. Leverage Profile Support (#20131): Instead of a single config, the failover logic would switch between the profiles/buckets proposed in #20131.
  2. Automate the Retry Loop (#46959): Rather than requiring users to build their own "OnApiRetry" hooks to trigger external wrapper scripts, the harness should natively handle the provider-switch during the retry cycle.
  3. Implement the "Sidecar" Philosophy (#40183): This brings the "Sidecar" model of capacity protection to the client side, ensuring that the developer is shielded from infrastructure fragility.

Suggested Implementation:
A failover_policy in settings.json:
{
"failover_policy": {
"enabled": true,
"primary_profile": "work",
"secondary_profile": "openrouter-backup",
"triggers": [500, 502, 503, 504, 429],
"max_failover_attempts": 1
}
}

Why this matters:
As highlighted by the users in #40771, Claude Code is being used to build complex, self-healing systems. The tool itself should embody these same engineering principles—resilience, redundancy, and graceful degradation. By implementing client-side failover, Anthropic ensures that Claude Code remains a reliable professional tool even when the
underlying infrastructure is under extreme pressure.

Proposed Solution

I'd like to be able to use a single config, or hierarchical configs, to define multiple logins and endpoints, and have hooks available to intercept http errors and redirect based on configuration settings.

Alternative Solutions

Writing my own, but the hooks for web failures (500, 401) aren't available in the api, so looking to implement my own proxy to intercept and redirect.

Re: Critical - Blocking my work below
This is the 2nd time in 2 weeks that Anthropic has had an outage preventing the current AI work. And there are 3-4x/week that I need to switch between accounts due to usage.

Priority

Critical - Blocking my work

Feature Category

API and model interactions

Use Case Example

Working on a longer term interaction with claude, and start getting 500 errors back from Anthropic (2026-04-15@12:00ET)

 Update - Claude.ai and Platform are down. Login for Claude Code does not work via Claude.ai.
Apr 15, 2026 - 15:40 UTC
Update - The Claude API has fully recovered as of 8:01 PT / 16:01 UTC. We are currently working on mitigating the ongoing errors for Claude AI. Claude Code users who are logged in are still able to use it, but logging in is still broken.
Apr 15, 2026 - 15:20 UTC
Identified - The issue has been identified and a fix is being implemented.
Apr 15, 2026 - 15:03 UTC
Update - We are continuing to investigate this issue.
Apr 15, 2026 - 14:55 UTC
Investigating - We are seeing increased errors on Claude.ai, API, and Claude Code
Apr 15, 2026 - 14:53 UTC

Having the ability to fail over to a different endpoint or configuration would allow claudecode to continue working on solutions, albeit, likely slower. It would also allow claude to remain able to answer questions, perhaps on ways to diagnose the issue to ensure it's not a isolated problem.

For multiple accounts, currently using multiple .claude* directories each with different configurations to different models/endpoints. While this allows the ability to "easily" switch accounts, context is lost and has to be rebuilt before continuing is possible.

Additional Context

_No response_

View original on GitHub ↗

5 Comments

0xbrainkid · 6 months ago

Client-side failover for API availability is a meaningful gap — single-provider dependency is a real reliability risk for production use, and the March 2026 outage demonstrated that internal retries cannot solve provider-level capacity events.

One dimension worth including in the failover policy design: identity continuity across provider switches. When Claude Code fails over from Provider A to Provider B mid-session, the conversation context migrates but the API credentials do not necessarily identify the same agent to both providers. For use cases where the API key encodes agent identity or authorization scope (enterprise deployments, team accounts with per-agent rate limits), a transparent failover that presents different credentials to different providers may behave differently at the capability level.

A minimal addition to the failover_policy schema:

{
  "failover_policy": {
    "enabled": true,
    "profiles": ["primary", "openrouter_backup"],
    "identity_policy": "preserve",
    "trigger_errors": ["5xx", "429"],
    "agent_id": "claude-code-agent-xyz"
  }
}

identity_policy: "preserve" means the failover attempt includes the same agent identity header (X-Agent-ID) regardless of which provider is being used — so any provider that honors agent identity can attribute the session correctly. identity_policy: "provider_native" falls back to provider-specific auth only.

The Sidecar philosophy framing is right — client-side protection from infrastructure fragility should be opaque to the workflow layer.

sahuagin · 6 months ago

Current information to show current end-user experience.

● Good, pushed. Now let's set up the project structure.

● Bash(cd ~/src/changed_to_protect && cargo init src --name changed_to_protect 2>&1)
  ⎿      Creating binary (application) package
     note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
  ⎿  API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"},"request_id":"req_01truncated"} · check status.claude.com

✻ Baked for 9m 17s

❯ we should probably create a jail for doing the development of this; we'll be able to install whatever we need without interrupting the host.
  ⎿  API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"},"request_id":"req_0truncated"} · check status.claude.com

❯ we should probably create a jail for doing the development of this; we'll be able to install whatever we need without interrupting the host.
  ⎿  API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"},"request_id":"req_0truncated"} · check status.claude.com

❯ major outage in claude status; wasn't anything showing earlier.

● Good timing on the outage note — nothing to worry about on our end since we just pushed.

  Let me look at the spline jail config to understand the pattern before setting up a warden dev jail.

  Listed 1 directory (ctrl+o to expand)
  ⎿  API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"},"request_id":"req_01truncated"} · check status.claude.com

❯ you work at all? There are manual ways, perhaps, to route around the anthropic outage. Not sure how to get you to continue though.
  ⎿  Please run /login · API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid authentication
     credentials"},"request_id":"req_011truncated"}

❯ you work at all? There are manual ways, perhaps, to route around the anthropic outage. Not sure how to get you to continue though.
  ⎿  Please run /login · API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid authentication
     credentials"},"request_id":"req_011truncated"}

❯ you alive again buddy?
  ⎿  Please run /login · API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid authentication
     credentials"},"request_id":"req_01truncated"}

❯ you alive again buddy?
  ⎿  Please run /login · API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid authentication
     credentials"},"request_id":"req_01truncated"}

❯ you alive again buddy?
  ⎿  Please run /login · API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid authentication
     credentials"},"request_id":"req_01truncated"}

❯ you alive again buddy?
  ⎿  Please run /login · API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid authentication
     credentials"},"request_id":"req_01truncated"}

This shows that there are intermittent failures early enough to have made a decision to redirect, and then later even though it is already logged in, it's still refusing the former credentials.

sahuagin · 6 months ago

Current information to show current end-user experience.

● Good, pushed. Now let's set up the project structure.

● Bash(cd ~/src/changed_to_protect && cargo init src --name changed_to_protect 2>&1)
  ⎿      Creating binary (application) package
     note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
  ⎿  API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"},"request_id":"req_01truncated"} · check status.claude.com

✻ Baked for 9m 17s

❯ we should probably create a jail for doing the development of this; we'll be able to install whatever we need without interrupting the host.
  ⎿  API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"},"request_id":"req_0truncated"} · check status.claude.com

❯ we should probably create a jail for doing the development of this; we'll be able to install whatever we need without interrupting the host.
  ⎿  API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"},"request_id":"req_0truncated"} · check status.claude.com

❯ major outage in claude status; wasn't anything showing earlier.

● Good timing on the outage note — nothing to worry about on our end since we just pushed.

  Let me look at the spline jail config to understand the pattern before setting up a warden dev jail.

  Listed 1 directory (ctrl+o to expand)
  ⎿  API Error: 500 {"type":"error","error":{"type":"api_error","message":"Internal server error"},"request_id":"req_01truncated"} · check status.claude.com

❯ you work at all? There are manual ways, perhaps, to route around the anthropic outage. Not sure how to get you to continue though.
  ⎿  Please run /login · API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid authentication
     credentials"},"request_id":"req_011truncated"}

❯ you work at all? There are manual ways, perhaps, to route around the anthropic outage. Not sure how to get you to continue though.
  ⎿  Please run /login · API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid authentication
     credentials"},"request_id":"req_011truncated"}

❯ you alive again buddy?
  ⎿  Please run /login · API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid authentication
     credentials"},"request_id":"req_01truncated"}

❯ you alive again buddy?
  ⎿  Please run /login · API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid authentication
     credentials"},"request_id":"req_01truncated"}

❯ you alive again buddy?
  ⎿  Please run /login · API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid authentication
     credentials"},"request_id":"req_01truncated"}

❯ you alive again buddy?
  ⎿  Please run /login · API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid authentication
     credentials"},"request_id":"req_01truncated"}

This shows that there are intermittent failures early enough to have made a decision to redirect, and then later even though it is already logged in, it's still refusing the former credentials.

sahuagin · 6 months ago

"Closed by mistake! I intended to add more context regarding the current outage. Please reopen this if possible, or I will open a new one referencing this discussion."

github-actions[bot] · 5 months ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.

Related Claude Code issues

Matched on shared title terms, labels, topic and reported release — ranked so issues with real discussion come first.

Browse by topic

Same class of failure, ranked by community engagement — this issue is one of many, so it may not appear in the visible list: Rate limit errors, Hooks & automation

Browse all Claude Code issue topics →