Claude Code 529 Overloaded: What It Retries For You, and What It Won't

Two things worth knowing before you do anything about a 529.

It is not your usage limit, and it does not count against your quota. It means the API is at capacity across all users right now. Nothing is wrong with your account, your key, or your request.

It has already been retried. By the time an overloaded error reaches you, Claude Code has tried up to ten times with exponential backoff:

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.

So hammering the same prompt achieves nothing except joining the queue behind everyone else doing the same thing. The useful moves are different.

Switch model before you retry

Capacity is tracked per model. A 529 on one model doesn't mean the others are saturated, so /model is a more productive response than retrying:

/model

This is the single highest-value thing in this post if you're blocked right now. Most people retry the same model repeatedly because the error doesn't mention that capacity is per-model.

What gets retried automatically, and what doesn't

Transient failures are retried up to 10 times with exponential backoff before anything surfaces. Knowing the boundary tells you whether waiting will help.

Retried for you:

• Server errors, overloaded responses and timeouts that arrive before any response has streamed
• Connections dropped before Claude completes any part of its response, thinking included
• Stalled streams where nothing has arrived yet
• Temporary 429 throttles
• Requests exceeding the context limit — retried with a reduced max_tokens

Deliberately not retried:

• TLS certificate validation failures — reported on the first attempt so you can fix them immediately rather than watching ten silent retries
• Mid-stream failures after Claude has started text or tool calls — the completed work is kept instead
• Failures arriving after the response finished — the response is kept and the turn ends normally
• Policy check denials — the denied request is never re-sent to the same model or a fallback
• Spend-limit 429s — a gateway marks these x-should-retry: false, and they aren't capacity problems

That mid-stream rule is the one people misread as a bug. If Claude got halfway through and the connection died, you'll see something like:

API Error: Connection lost mid-response. The response above may be incomplete.

The completed work was kept rather than discarded to start over. Reply continue and it resumes from the last completed block. In non-interactive mode with -p, it does that automatically up to three times before giving up.

While it is retrying, the spinner tells you where you are:

Retrying in Ns · attempt x/y

And if nothing arrives for 20 seconds while a request is pending, you get a network hint rather than silence. (During advisor review that banner waits 90 seconds instead, because advisors legitimately take longer.)

The flag that keeps unattended runs alive

This is the part missing from most 529 write-ups, and it's the direct answer to issue #60577 — transient capacity errors aborting long-running tasks with no auto-recovery.

If you run unattended — scheduled jobs, CI, long agentic tasks you walk away from — ten retries is not enough, because a capacity blip can outlast the backoff window. Set:

CLAUDE_CODE_RETRY_WATCHDOG=1

In unattended sessions that retries 429 and 529 capacity errors indefinitely, and raises the retry count for other transient errors to 300, which is roughly three hours of backoff. It also removes the CLAUDE_CODE_MAX_RETRIES cap entirely.

The related knobs:

Don't set the watchdog for interactive work. Sitting through three hours of backoff at your keyboard is worse than seeing the overloaded error and switching model.

Request timed out is a different problem

Ten minutes is the default per-request timeout. If you're hitting it, the cause is usually one of three things, and only one is fixed by raising the limit:

• The model is generating a very large response — break the work into smaller prompts instead
• A slow network or proxy — this is the case where raising API_TIMEOUT_MS is the right call
• High load — retry, or switch model

Reaching for API_TIMEOUT_MS when the real cause is an oversized task just means waiting longer for the same failure.

Session limits look similar and aren't

A capacity error and a usage limit produce different messages, and conflating them sends you down the wrong path:

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm

Session and weekly limits are shared across all models, so /model won't rescue you there. But Opus limit and Sonnet limit apply only to that model family — switching does work for those. Usage counts against session and weekly allowances simultaneously.

Since v2.1.234, an interactive session on a claude.ai subscription can wait it out instead:

Usage limit reached · continuing automatically at 3:45pm · esc to cancel

Press Esc at an empty prompt to cancel the wait. You can toggle it under /config → Continue automatically at usage limit, and separately in the Desktop app's Code tab — they're independent settings.

If limits are what you keep hitting rather than capacity, the causes are worth understanding separately; I went through them in why Claude Code burns tokens while you're not even using it.

A quick triage order

1. Read the message. Capacity (529), rate limit (429), timeout and usage limit are four different problems.
2. If it's a 529 overloaded error — /model first, don't retry the same one.
3. Check status.claude.com for an active incident before debugging your own setup.
4. If it happened mid-response, reply continue rather than re-running the whole task.
5. For unattended runs, set CLAUDE_CODE_RETRY_WATCHDOG=1 so a blip doesn't kill a three-hour job.
6. Run /status to confirm which credential is actually active — a 429 often traces to the wrong one.

The pattern worth internalising: most of these errors are already being handled for you, and the ones that aren't are unhandled on purpose — because retrying would throw away work or re-send something that was denied. Knowing which bucket you're in turns a vague "the API is broken" into a two-second decision.

If the symptom is the CLI feeling sluggish rather than erroring, that's a separate class of problem — Claude Code slow, hanging, or eating memory covers the silent ones, including a search failure that reports itself as healthy. Managing what these tools carry into a session is the problem ContextZero came out of.