Claude Code 529 Overloaded: who sent it and how to fail over

Claude Code stops mid-task, after a long spinner, with this:

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

The advice in the message has already been followed: by default Claude Code retries an overloaded response up to 10 times, with exponential backoff, before it shows you anything.

A 529 is not your quota, your key or your prompt. It is a capacity problem on the serving side, and the useful questions are which service ran out, and whether you have somewhere else to send the request.

What a 529 actually means

Anthropic's API returns HTTP 529 with the error type overloaded_error when it is temporarily overloaded, and its error reference says this can happen under high traffic across all users. Claude Code's own error reference adds two things: a 529 does not count against your usage limit, and capacity is tracked per model.

That last point is the practical one. Opus can be saturated while Sonnet answers normally, which is why Claude Code sometimes shows a more specific line:

Opus is experiencing high load, please use /model to switch to Sonnet

Do not confuse a 529 with a 429. A rate_limit_error means your organization crossed a limit, and it needs a different fix; see the rate limit guide. Anthropic also notes that a sharp jump in your own usage can produce 429s from acceleration limits: that is a rate limit, not an overload.

A 529 arrives in one of two shapes:

• Before any output. The request fails outright with HTTP 529, and Claude Code retries it.
• In the middle of a stream. The API has already answered 200 and started streaming, then sends an error event:

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

If Claude had not started any text or tool call yet, Claude Code retries this too. Once Claude has completed a block of text or a tool call, it does not re-send, because that could run the same tool calls twice. Since v2.1.199 it keeps what Claude completed, runs the tool calls Claude finished, and shows API Error: Server error mid-response. The response above may be incomplete. Earlier versions discarded the whole turn. An interrupted final block is dropped, so read what is on screen, then reply continue.

Who actually returned it

The last sentence of Claude Code's message tells you where to look, and it changes with your setup:

• Anthropic API (a subscription or an API key): it names status.claude.com.
• Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry: it names that provider's status page.
• A custom ANTHROPIC_BASE_URL: it names the gateway's host.

The third case is where people lose time. The message points at your gateway, but a gateway that passes errors through hands Claude Code the upstream's status unchanged, so the 529 can still be Anthropic's, one hop further away.

If the gateway is kRouter, you can settle it quickly:

• kRouter does not create 529s. One that reaches Claude Code through kRouter is an upstream provider's 529, passed on after kRouter ran out of alternatives -- sometimes one it received earlier, repeated while every account for that model is still cooling down.
• kRouter's own failures look different. No active account for a provider gives a 503 saying No active credentials for provider; network failures come back as 502.
• The log names the account. The dashboard's Console Log page shows each failover as [AUTH] Account <name> unavailable (529), trying fallback, and combos add Model <model> failed, trying next.
• The final error names the route. When every account for a model is cooling down, the message starts with the provider and model in square brackets and ends with how long until the first cooldown ends. When a whole combo fails, the status code comes from the first entry that failed and the message from the last one, so trust the log over the message.

What does not work

Retrying by hand straight away. Claude Code has just done that, up to ten times. Wait, or change model.

Logging in again, a new API key, a second Claude account. None of these touches capacity. A subscription and an API key both end at Anthropic's API, and a 529 reflects load across all users, so a second login usually gets the same answer. Extra accounts help with 429s, rarely with a 529.

Shortening the prompt. Request size is not the cause. An oversized request fails with a 413 or a context-length error instead.

Raising CLAUDE_CODE_MAX_RETRIES. It makes Claude Code wait longer before telling you, and it is capped at 15. CLAUDE_CODE_RETRY_WATCHDOG=1 keeps retrying 429 and 529 capacity errors instead of failing, which suits a CI job nobody is watching. In an interactive session it just means a longer spinner.

Fix 1: change model, or let Claude Code change it for you

Since capacity is per model, the cheapest fix is to move off the saturated one. Run /model and pick another.

To make that automatic, give Claude Code a fallback chain. For one session:

claude --fallback-model sonnet,haiku

Or permanently, in your settings file:

{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

When the primary model is overloaded or unavailable, Claude Code tries these in order, at most three, and shows a notice when it switches. The switch lasts only for the current turn, so your next message goes to the overloaded model first again. The chain never triggers on rate-limit, authentication or billing errors.

If Anthropic is your only provider, this is the whole fix. You do not need a router for it.

Fix 2: a second route when every Claude model is busy

A fallback chain stays inside one service and resets every turn. When the overload is broad, you need a route that ends somewhere else.

Claude is not only served by Anthropic's API: GitHub Copilot and Kiro both offer Claude models, for example. Those routes have their own limits and model lists -- Copilot deprecated several older Claude models across most of its features on September 1, 2026 -- and none is guaranteed to have room when Anthropic's API is full. That is why the last entry in the combo below is not Claude at all. A local router puts them all behind the one endpoint Claude Code already talks to:

npm install -g @sifxprime/krouter
krouter -t

Open http://localhost:20128/dashboard, connect the providers you have, then go to Combos and click Create Combo:

Combo: claude-529-safe
  1. cc/claude-opus-4-8      your Claude subscription
  2. cc/claude-sonnet-4-6    same account, other model: capacity is per model
  3. gh/claude-haiku-4.5     Claude through GitHub Copilot
  4. glm/glm-5.3             not Claude: the last resort

Use whichever model ids your dashboard lists; these are examples. Then open CLI Tools, expand Claude Code, click Select Model next to the slot you use (Claude Opus or Claude Sonnet), pick the combo and click Apply. That writes ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN and the model slots into ~/.claude/settings.json. By hand, with a key from the dashboard's Endpoint page:

export ANTHROPIC_BASE_URL=http://localhost:20128/v1
export ANTHROPIC_AUTH_TOKEN=<your-krouter-key>
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-529-safe

Here is what kRouter does with an overloaded response:

• It reads the words, not just the code. Any error whose message contains "overloaded" or "capacity" gets the overload treatment, so a provider that reports overload as a 503 is caught too. (A 503 first gets up to three quick retries on the same account; a 529 gets none.)
• It parks the model, not the account. That model on that account gets a cooldown: until the retry time the response names, if any, otherwise 2 seconds, doubling with each consecutive failure up to 5 minutes. Other models on the account stay usable.
• It moves on straight away, to the provider's other connected accounts, then to the next combo entry.
• It remembers. While the cooldown runs, later requests skip the overloaded entry without a round trip; one success resets the backoff. A per-turn fallback chain cannot do this.
• It stops hammering a provider that is down. Ten 5xx responses in a row from one provider open a circuit breaker for five minutes, and requests to it fail at once with a 502 saying Circuit breaker open for provider. The breaker covers the whole provider, so a long run of Opus 529s can bench cc/claude-sonnet-4-6 too. That is why entries 3 and 4 go elsewhere.

kRouter also moves an entry ahead when its provider reports remaining quota for that exact model, most quota first, so the order you type is a preference rather than a guarantee. The combos docs cover the details.

Where kRouter is not the answer

It cannot switch mid-stream. Failover happens before the reply starts. Once Anthropic has begun streaming, an overloaded event goes straight to Claude Code, and Claude Code's own rules apply.

A combo that only reaches Anthropic adds little. It does what fallbackModel does, plus remembering the cooldown between turns. When the overload covers every Claude model, it has nowhere to go.

Fallback models are different models. A non-Claude model has a different context window and different tool-calling habits. Read the context window guide and the open-model comparison first.

Prompt caches do not travel. A cache built on one account or provider does not exist on the next, so the first request after a switch gets no cache hit.

Subscriptions carry account risk. The dashboard shows a Risk Notice before you connect Claude Code, GitHub Copilot or Kiro: those sessions are not licensed for proxy use, and the account may be restricted or banned.

Google's "No capacity available" is not treated like a 529. kRouter assumes another account cannot fix it: unless Google names a retry time, it does not try your other accounts, and a combo hands the error back to you instead of moving on. The errors reference covers it.

Working out what you are looking at

Common questions

Does a 529 count against my Claude usage limit?

No. Claude Code's error reference says a 529 is not your usage limit and does not count against your quota. It means the API is temporarily overloaded.

How long does a Claude 529 overload last?

Anthropic does not publish a typical duration; Claude Code's message only says it is usually temporary. Check status.claude.com for a posted incident, or switch model with /model, since capacity is tracked per model.

Why does the error name my gateway instead of Anthropic?

With a custom ANTHROPIC_BASE_URL, Claude Code names the gateway's host. A gateway that passes errors through still returns the upstream's 529, so check the gateway's log for which provider and account sent it. kRouter never generates a 529 itself.

Will adding another Claude account stop 529 errors?

Usually not. A 529 reflects load across all users, so a second login on the same API tends to get the same answer. For a 529 you need a different model, or a different route to one.

Does Claude Code have a built-in fallback for overloaded models?

Yes. The --fallback-model flag or the fallbackModel setting lists up to three models to try when the primary is overloaded or unavailable. It applies to the current turn only, and it does not trigger on rate-limit errors.

Related

• Claude Code "rate limit exceeded": every cause and the fix
• Anthropic rate limits explained: tiers, spend caps, 429s
• "No capacity available" and "Overloaded" errors
• Combos and fallback
• ANTHROPIC_BASE_URL: point Claude Code at any model