Troubleshooting
Claude Code 529 Overloaded error: what it means and what to do
When Claude Code shows API Error: 529 Overloaded or overloaded_error, Anthropic's API is temporarily at capacity. It is not your usage limit and not a problem with your setup. This page covers what the status code means, how it differs from 429 and 500, what Claude Code already retries for you, and what you can do. It follows Anthropic's API errors page and the Claude Code error reference, checked on November 5, 2026.
- Anthropic's API errors page defines 529 as
overloaded_error: "The API is temporarily overloaded." - A 529 can occur when the API has high traffic across all users. Claude Code's docs say it is not your usage limit and does not count against your quota.
- Claude Code retries by itself, up to 10 times by default, before it shows the error.
- What to do: check status.claude.com, try again in a few minutes, or run
/modeland switch to another model, since capacity is tracked per model.
What 529 Overloaded means
Anthropic's API errors page lists the status code and error type together. The row for this error reads:
529 - overloaded_error: The API is temporarily overloaded.The same page adds a warning: "A 529 error can occur when the API experiences high traffic across all users." Claude Code's error reference describes it the same way: the API is temporarily at capacity across all users, and Claude Code has already retried several times before showing the message. It also states that "A 529 is not your usage limit and doesn't count against your quota."
The message you see in the terminal looks like this, from Claude Code's error reference:
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 last sentence varies by provider. Claude Code may also show Opus is experiencing high load, please use /model to switch to Sonnet when one model is under particularly high load.
529 vs 429 vs 500
These are different errors with different causes. The definitions below are from Anthropic's API errors page.
| Status | Type | Meaning |
|---|---|---|
| 429 | rate_limit_error | Your organization has hit a rate limit, reached its usage tier's monthly spend cap, or reached a spend limit on the Claude Code workspace. |
| 500 | api_error | An unexpected error has occurred internal to Anthropic's systems. Retry with exponential backoff; if it persists, contact support with the request ID. |
| 529 | overloaded_error | The API is temporarily overloaded. |
The practical difference: a 429 is about your own limits, so reducing your traffic or raising the limit helps. A 529 is about the API's capacity across all users, so nothing in your account causes it. The API errors page notes one overlap: "In rare cases, if your organization has a sharp increase in usage, you might see 429 errors because of acceleration limits on the API," and advises increasing traffic gradually and keeping usage consistent.
The API errors page does not list a 503 row. Claude Code's error reference says it shows the status code and the API's error message for any 5xx response, so a 5xx other than 529 is reported with its own code and message.
What Claude Code retries for you
Claude Code retries transient failures up to 10 times with exponential backoff before it shows you an error. Overloaded responses are among the failures it retries. While it retries, the spinner shows a Retrying in Ns · attempt x/y countdown. So when you finally see the 529 message, the retries that apply have already happened.
Retrying can stop earlier on 529 errors. Anthropic's environment variables page gives an example: with an API key on an Opus model, it stops at the third 529 and shows the repeated 529 message. If you set a fallbackModel, Claude Code switches to that model instead of showing the error. The settings reference describes fallbackModel as naming backup models to try, in order, when the primary model is overloaded or unavailable.
Environment variables for retries
These names and defaults come from Claude Code's error reference. A retry variable you set applies to the whole session, so use them with a purpose.
| Variable | Default | Effect |
|---|---|---|
CLAUDE_CODE_MAX_RETRIES | 10 | Number of retry attempts. Lower it to surface failures faster in scripts. |
CLAUDE_CODE_RETRY_WATCHDOG | unset | Set to 1 in unattended sessions such as CI jobs to retry 429 and 529 capacity errors indefinitely instead of failing after CLAUDE_CODE_MAX_RETRIES attempts. |
CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS | 500 | Starting delay of the backoff between retries of a 529. Can be raised up to 32000. Requires Claude Code v2.1.292 or later. |
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS | 32000 | Ceiling on that backoff. Can be raised up to 64000. Requires Claude Code v2.1.296 or later. |
API_TIMEOUT_MS | 600000 | Time each request attempt has to receive its response headers. It does not limit how long a streaming response runs after that. |
For example, to let an unattended job wait through a capacity problem rather than fail:
export CLAUDE_CODE_RETRY_WATCHDOG=1$env:CLAUDE_CODE_RETRY_WATCHDOG = "1"With the watchdog set, the two overloaded-delay variables have no effect, according to the same reference.
Check Anthropic's status
Claude Code's error reference tells you to check status.claude.com for capacity notices. Claude Code also names where to check during retries: on the Anthropic API, a 529 retry line names status.claude.com. If you use Claude Code through a relay, the relay has its own status page; CoreCode's is at /status/.
What you can do
- Wait a few minutes and send the message again. Claude Code's reference says to try again in a few minutes.
- Check the status page for a capacity notice, as above.
- Switch model with
/model. Capacity is tracked per model, so another model may work while one is under high load. Claude Code prompts you to do this when it detects high load on a model. - Set a fallback model. The
fallbackModelsetting lets Claude Code move to a backup model on its own when the primary is overloaded. - Ramp traffic up gradually. The API errors page advises increasing traffic gradually and keeping usage consistent, which concerns the 429 acceleration-limit case.
If you call the API from your own code, Anthropic's official SDK automatically retries transient failures, including 5xx errors, with exponential backoff, twice by default. The retry count is configurable with max_retries in the SDK client.
If you use Claude Code through CoreCode
CoreCode is a relay answered by official Claude accounts. Claude Code points at it with ANTHROPIC_BASE_URL=https://corecode.live and the key in ANTHROPIC_AUTH_TOKEN, as set out in the Claude Code setup guide. CoreCode's errors page says this about 529: Anthropic is temporarily overloaded; your setup is not the cause, and Claude Code retries by itself. If it lasts more than a few minutes, check service status, or switch models for a while with /model.
For other statuses, the same page covers 429 (a key over its request rate or concurrency limit) and 5xx errors, including the 503 that CoreCode returns while it is releasing, which carries Retry-After: 5.
FAQ
What does Claude Code 529 Overloaded mean?
It means Anthropic's API is temporarily overloaded. Anthropic's API errors page defines 529 as overloaded_error: "The API is temporarily overloaded." It can occur when the API has high traffic across all users, so your own setup is not the cause.
Is the Claude Code API Error 529 my usage limit?
No. Claude Code's error reference says a 529 is not your usage limit and does not count against your quota. A rate limit is a 429 rate_limit_error, which is a separate error.
Does Claude Code retry a 529 by itself?
Yes. Claude Code retries transient failures up to 10 times with exponential backoff before showing an error, and overloaded responses are among the failures it retries. You can change the count with CLAUDE_CODE_MAX_RETRIES, or set CLAUDE_CODE_RETRY_WATCHDOG=1 for unattended sessions that should keep retrying 429 and 529 errors.
How do I check whether Claude Code is overloaded today?
Open status.claude.com, which Claude Code's error reference names for capacity notices. If you use CoreCode, its own status is at /status/.
What is the difference between 529 and 429 in Claude Code?
A 429 rate_limit_error means your organization hit a rate limit or a spend cap. A 529 overloaded_error means the API is at capacity across all users. Reduce your own traffic for a 429; for a 529, wait, check the status page, or switch model with /model.
Can I switch models when Claude Code reports overloaded?
Yes. Run /model and pick another model. Claude Code's error reference says capacity is tracked per model, so a different model can keep working while one is under high load.
Sources
- Claude API: Errors (529 overloaded_error row, warning about high traffic, 429 and 500 definitions, SDK retries; checked November 5, 2026)
- Claude Code: Error reference (Repeated 529 Overloaded errors, automatic retries, tune retry behavior; checked November 5, 2026)
- Claude Code: Environment variables (CLAUDE_CODE_MAX_RETRIES and the retry watchdog and overloaded delay variables; checked November 5, 2026)
- Claude Code: Settings reference (fallbackModel; checked November 5, 2026)
- Claude status (Anthropic's status page; checked November 5, 2026)