Claude Code Error 529 (Overloaded): What It Means and How to Fix It
By Neo Zino - builder of ClockedCode10 min readClaude Code error 529 (overloaded) means Anthropic's API is briefly at capacity, not a broken install - what it means, why it clears itself, and real fixes.
Made with DispatchSEO
On this page
Claude Code error 529 means Anthropic's API is temporarily out of capacity - Anthropic's own error reference calls it overloaded_error, and it isn't caused by your prompt, your CLAUDE.md, or a broken install. By the time you see the message, Claude Code has already retried the request automatically, up to ten times by default, and a 529 never counts against your usage limit or spend cap.
TL;DR: A 529 almost always clears on its own within a retry or two - Claude Code just did most of that retrying silently before showing you anything. If it keeps happening, check status.claude.com for a capacity incident, run
/modelto switch to a less-loaded model, and for CI or unattended runs setCLAUDE_CODE_RETRY_WATCHDOG=1so it keeps retrying instead of giving up.
Is 529 your fault, or is Anthropic just busy
Anthropic's API error reference lists 529 - overloaded_error with one line of explanation: "The API is temporarily overloaded." It sits alongside a warning worth reading closely, because it explains a mix-up that shows up constantly in the threads ranking for this exact error:
529 errors can occur when the API experiences high traffic across all users. In rare cases, if your organization has a sharp increase in usage, you might see 429 errors because of acceleration limits on the API.
In other words: a 529 is Anthropic-wide capacity strain, and a sudden burst of 429s from your own account is a separate, account-side acceleration limit - the fix for one isn't the fix for the other, and mixing them up is why some advice online tells you to "slow down" for an error that has nothing to do with your usage.
Claude Code's own error reference is more specific about what shows up on screen:
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.
That message only appears after Claude Code has already tried and failed several times - the cause listed in its own docs is blunt about it: "Claude Code has already retried several times before showing this message." And per the same reference, a 529 never counts against your quota, so retries here don't cost you anything except time.
What Claude Code already tried before you saw this error
Three retry budgets, stacked - Claude Code's is the one that matters
2
retries by default
Raw Anthropic SDK
The bare API client's own default before it gives up and raises.
10
retries, capped at 15
Claude Code (default)
What you're actually running into - this is why 529 usually clears before you see it.
~300
retries, ~3h backoff
CLAUDE_CODE_RETRY_WATCHDOG=1
Opt-in for CI/unattended jobs - keeps retrying 529/429 capacity errors indefinitely.
Source: code.claude.com's error reference, checked 2026-09-05.
The raw Anthropic SDK retries transient failures like 5xx errors and connection drops twice by default before raising an exception to your code. Claude Code sets its own, much larger budget on top of that: CLAUDE_CODE_MAX_RETRIES defaults to 10, capped at 15, with exponential backoff between attempts. That gap is the whole reason 529 usually resolves itself - you're not seeing the SDK's two-try ceiling, you're seeing what's left after ten tries already failed.
For unattended sessions - a CI job, a scheduled headless run - even 15 retries can still land you mid-incident with nothing to show for it. CLAUDE_CODE_RETRY_WATCHDOG exists for exactly that case:
export CLAUDE_CODE_RETRY_WATCHDOG=1
Set to 1, it raises the retry budget for 529 and 429 capacity errors to roughly 300 attempts with backoff spread across about three hours, while still failing immediately on a spend-limit 429 (see the FAQ) rather than burning three hours on an error that will never clear on its own.
Both retry settings, along with the per-request timeout, live in the env block of your project or user settings.json:
{
"env": {
"CLAUDE_CODE_MAX_RETRIES": "15",
"API_TIMEOUT_MS": "1200000"
}
}
API_TIMEOUT_MS defaults to 600000 (10 minutes) per request, and each retry gets its own full timeout window - so a worst-case run at the defaults can legitimately take well over an hour before it finally gives up. If you'd rather not hand-edit that file, ClockedCode's settings.json generator builds the whole thing from checkboxes instead.
Checking whether it's a wider outage
Once you see the error, check things in this order
Open status.claude.com
Confirms a broad capacity incident, not just your session
Run /model and switch
Capacity is tracked per model - a busy one doesn't mean they all are
Check your spend cap
A spend-limit 429 looks similar but never clears on its own
Run /feedback if it persists
Reports the exact session to Anthropic once retries are exhausted
status.claude.com is the fastest way to rule out a broad incident - it tracks Claude.ai, the Claude API, and Claude Code as separate components, so you can confirm whether the API specifically is degraded rather than guessing from a single error message. If it's clean, /model is worth trying next: capacity gets tracked per model on Anthropic's side, so a busy flagship model doesn't necessarily mean every model is busy.
Fixes that shorten the wait
Most of the actual fixing already happened by the time you read the error - Claude Code retried, and either it worked or the incident is real. What's left for you to do:
- Wait it out. A minute or two covers the overwhelming majority of 529s; Anthropic's own guidance for the underlying
api_errorandoverloaded_errorcases is to retry with backoff, which Claude Code is already doing. - Switch models with
/model. Since capacity is tracked per model, this is the one manual action that can genuinely route around a busy model instead of just waiting on the same one. - Rule out a spend cap, not a capacity issue. A 429 reporting a spend limit is never retried automatically and never clears on its own - if that's what you're hitting, no amount of waiting on a 529 fixes it. Check your usage settings in the Claude Console directly.
- Raise the retry budget for long or unattended runs. If you're running Claude Code as a background task or a scheduled job,
CLAUDE_CODE_RETRY_WATCHDOG=1is the setting built for exactly that - it keeps a capacity error from silently ending a job three hours before the incident clears. - Time genuinely long jobs for off-peak hours if 529s are a recurring pattern for you specifically, since traffic-driven capacity strain isn't evenly distributed across the day.
529 vs the other errors that look just like it
| Code | Type | What it means | Claude Code auto-retries it |
|---|---|---|---|
| 400 | invalid_request_error | Malformed request, or an org/workspace spend limit | No |
| 401 | authentication_error | Bad, expired, or revoked API key | No |
| 429 (throttle) | rate_limit_error | Temporary rate limit or acceleration limit | Yes, within the retry budget |
| 429 (spend limit) | rate_limit_error | A configured spend cap was reached | No - fails immediately |
| 500 | api_error | Unexpected internal Anthropic error | Yes |
| 504 | timeout_error | Request didn't finish before the connection deadline | Yes, as a timeout retry |
| 529 | overloaded_error | API is temporarily out of capacity, Anthropic-wide | Yes, up to the configured budget |
The practical takeaway: everything Claude Code retries automatically shares one property - the request failed before any response started streaming back. The moment a response has already started, the handling changes completely, which is the next thing worth knowing before you assume you're looking at overload.
When it isn't overload at all
Repeated 529 overloaded errors
Terminal goes quiet while Claude Code retries in the background - it reads exactly like Anthropic is at capacity.
ANTHROPIC_API_KEY was never set
A documented GitHub issue: every request failed the same way, so it retried like an overload instead of failing fast like a config error.
That split comes from a real, documented Claude Code GitHub issue: a user's environment was missing ANTHROPIC_API_KEY, every request failed the same way, and Claude Code's retry loop treated the identical, non-transient failure as if it were transient capacity load. Nothing printed to the terminal while it retried, so the session looked stuck rather than misconfigured. If a 529-shaped problem never clears no matter how long you wait or how many times you restart, check your API key and auth setup before assuming it's Anthropic's capacity.
A few other things get misread as 529 for the same reason - the symptom looks similar, but the fix is completely different:
- Errors mid-response are handled differently on purpose. If a failure happens after Claude has already started streaming text or a tool call back to you, Claude Code does not auto-retry - it keeps the completed output and shows a notice, because re-sending could execute the same tool call twice. Replying
continuepicks up from the last completed block. - TLS certificate failures and organization-policy denials fail immediately, by design, so you can fix the actual problem instead of watching a retry loop that will never succeed.
- A hung MCP server or a corporate proxy can produce a stalled-looking session that has nothing to do with Anthropic's capacity at all - if you're behind a proxy or running custom MCP servers, Claude Code's MCP config is the place to check timeouts before blaming 529.
FAQ
What does Claude Code error 529 mean?
529 is Anthropic's overloaded_error - the API is temporarily out of capacity across all users, not just you. It isn't caused by your prompt, your CLAUDE.md, or a broken install, and it doesn't mean your account is doing anything wrong.
Does a 529 error count against my usage limit or spend cap?
No. Anthropic's documentation is explicit that a 529 does not count against your quota. If you're watching your spend cap or weekly limit tick down while also seeing 529s, the two are unrelated - check the cap separately.
How many times does Claude Code retry a 529 before I see it?
Ten, by default, capped at fifteen - far more than the raw Anthropic SDK's own default of two. That's why a transient 529 usually clears on its own before you ever see an error: Claude Code has already tried, and failed, up to ten times first.
How do I check if Anthropic's API is down right now?
Open status.claude.com. It reports live status for Claude.ai, the Claude API, and Claude Code separately, so you can confirm whether it's a broad capacity incident or isolated to your session before doing anything else.
Why do I see repeated 529 errors with no output at all, like the session is stuck?
That's usually the retry loop running quietly in the background, not a hang - but it's also the exact symptom a documented Claude Code bug report described for a missing ANTHROPIC_API_KEY, where every request failed identically and got retried as if it were overload. If it never clears, check your API key and auth setup before assuming it's capacity.
Can I make Claude Code keep retrying instead of giving up after 15 attempts?
Yes - set the CLAUDE_CODE_RETRY_WATCHDOG environment variable to 1. It's built for unattended CI jobs and raises the retry budget for 529 and 429 capacity errors to roughly 300 attempts (about three hours of backoff), while still failing immediately on spend-limit 429s and other non-capacity errors.
It's rarely worth acting on the first one
A single 529 is Claude Code telling you it already tried something on your behalf and failed - most of the time the right response is to just send the message again. Keep status.claude.com bookmarked for the times it isn't, and if you're setting up CLAUDE_CODE_MAX_RETRIES or the retry watchdog for a CI pipeline, my free settings.json generator writes the config for you instead of hand-editing JSON. If it's a different error message entirely, the claude: command not found guide covers the other one that trips up a fresh install.