Beta
Download

Claude 529 overloaded error: what it means and what to do

AutoRouter8 min read

Key facts

A 529 error from Claude means Anthropic's API is temporarily at capacity across all users, so the fault is on Anthropic's side and has nothing to do with your rate limit, usage limit or credit balance. The API returns it as HTTP 529 with the error type overloaded_error, and Anthropic describes it as something that "can occur when the API experiences high traffic across all users" (as of November 16, 2026). Claude Code retries a 529 on its own before it shows you anything, so by the time you read "Repeated 529 Overloaded errors", the fix is to wait a few minutes, check status.claude.com, or switch to another model. AutoRouter, the Mac app for Codex and Claude Code, wrote this post.

What does the Claude 529 overloaded error mean?

A 529 means the Claude API had no capacity for your request at that moment. It is one of the HTTP errors listed in Anthropic's error reference, with a JSON body whose error.type is overloaded_error and a request_id you can give support. Anthropic's Claude Code docs say the API is "temporarily at capacity across all users" when it happens, and that a 529 "is not your usage limit and doesn't count against your quota."

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "..."
  },
  "request_id": "req_..."
}

529 isn't a standard HTTP status code, so check the error.type field as well as the number. On the Claude API you also aren't charged for it, because Anthropic bills only successful API calls and says failed requests aren't charged.

How is a 529 different from a 429 rate limit error?

A 429 is about your organization's limits and a 529 is about Anthropic's capacity for everyone. A 429 rate_limit_error means your organization went over a rate limit (requests, input tokens or output tokens per minute), grew its usage too fast for its ramp limit, or reached its usage tier's monthly spend cap. Slowing down fixes a rate limit, and the response's retry-after header says how long to wait. A spend-cap 429 has no retry-after header and keeps failing until the next month or a higher tier, so retrying it never helps.

ErrorTypeWhose problemDoes retrying help?What to do
529overloaded_errorAnthropic's capacity, for all usersYes, after a waitWait, check status, or switch models
429 with retry-afterrate_limit_errorYour organization's rate or ramp limitYes, after the retry-after secondsSend requests more slowly, or ask for a higher tier
429 without retry-afterrate_limit_error (enforced_spend_limit_reached)Your usage tier's monthly spend capNo, until access resumesRequest a tier increase in the Claude Console
400 naming a spend limitinvalid_request_errorA spend limit you setNoRaise or remove your own limit
500api_errorAn unexpected failure inside AnthropicUsually, with backoffRetry; report it with the request ID if it persists

On a Claude subscription in Claude Code, a short throttle shows as API Error: Server is temporarily limiting requests (not your usage limit), and reaching your plan's limit shows its own message with a reset time. How Claude Code usage limits work covers those plan limits. Every row above comes from Anthropic's errors and rate limits docs, checked November 16, 2026.

What does Claude Code do when it gets a 529?

Claude Code retries a 529 up to 10 times with exponential backoff before it shows an error, according to its error reference (checked November 16, 2026). The first wait starts at 500 milliseconds and later waits are capped at 32 seconds. While it retries, the spinner shows a Retrying in Ns · attempt x/y countdown, and from the third attempt the line under it names the 529 and where to check service status. Only when every retry fails does Claude Code print API Error: Repeated 529 Overloaded errors.

When one model is under particularly high load, Claude Code also suggests a switch, for example Opus is experiencing high load, please use /model to switch to Sonnet. Five environment variables change the retry behavior:

VariableDefaultWhat it changes
CLAUDE_CODE_MAX_RETRIES10How many times Claude Code retries; lower it to fail faster in scripts
CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS500The first wait after a 529, up to 32,000
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS32000The longest wait between 529 retries, up to 300,000
CLAUDE_CODE_RETRY_WATCHDOGunsetSet to 1 in unattended jobs to retry 429 and 529 capacity errors indefinitely
CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MSunsetCaps how long each request waits out 429 and 529 errors with the watchdog on

The two overload delay variables need Claude Code v2.1.292 and v2.1.296 or later, and they have no effect when the watchdog is on. If you call the API from your own code, Anthropic's official SDKs retry 5xx errors twice by default with exponential backoff, and max_retries changes that.

How do I fix a 529 overloaded error in Claude Code?

You can't fix a 529 on your side, but you can keep working while Anthropic recovers. Anthropic's own advice for a repeated 529 is to check the status page, try again in a few minutes, or switch models, since capacity is tracked per model.

  1. Check the status page. Open status.claude.com, or the provider or gateway named in the error message if you don't use Anthropic's API directly.
  2. Wait, then send again. Your message is still in the conversation, so for a long prompt you can type try again instead of pasting it.
  3. Switch models. Run /model and pick another model, such as Sonnet when Opus is overloaded. The switch lasts until you change it back.
  4. Set a fallback chain. Start Claude Code with --fallback-model so it moves to the next model on its own when the primary one is overloaded. The switch covers the current prompt only.
  5. For unattended jobs, wait it out. Set CLAUDE_CODE_RETRY_WATCHDOG=1 in CI so a 529 doesn't fail the run.
# Try Sonnet, then Haiku, when the main model is overloaded (up to three models)
claude --fallback-model sonnet,haiku

# Keep a CI run waiting through 429 and 529 capacity errors
CLAUDE_CODE_RETRY_WATCHDOG=1 claude -p "run the test suite and fix failures"

To keep a fallback chain across sessions, set fallbackModel as an array in your settings, for example ["claude-sonnet-5", "claude-haiku-5-5"]. Claude Code doesn't confirm the chain at startup and /status doesn't show it; the notice when it switches is the first sign it's set. Rate-limit, billing and authentication errors never trigger a fallback. How to change the model in Claude Code covers /model and model aliases.

How can you tell if a 529 is you or Anthropic?

A 529 from the Claude API is always on Anthropic's side, so the useful question is which service returned it. The trailing sentence of Claude Code's error names where to look: status.claude.com on Anthropic's API, the cloud provider's status page on Amazon Bedrock, Google Cloud or Microsoft Foundry, or the gateway host when ANTHROPIC_BASE_URL points somewhere else.

Can you switch to a non-Claude model when Claude is overloaded?

Claude Code's built-in model aliases, such as opus, sonnet and haiku, all point at Claude models, so /model and fallback chains help when one Claude model is overloaded and another isn't. AutoRouter, the Mac app for Codex and Claude Code, adds 20+ models to Claude Code's /model picker, including models from providers other than Anthropic. On AutoRouter Pro ($50 a month as of November 16, 2026, with paid models billed at the provider's price plus 10%, from $20 of included usage and then credits), you can pick one of those while a Claude model is at capacity and switch back later. The models page lists them with their makers and prices.

Questions

Is Claude down when I get a 529?

Not necessarily: a 529 means the API was at capacity for that request, which can be brief and limited to one model. Check status.claude.com for the Claude API component. If it shows no incident and other models work, the overload is probably limited to the model you were using.

Does a 529 error count against my Claude usage limit?

No. Anthropic's Claude Code docs say a 529 doesn't count against your quota, and on the API failed requests aren't charged. Claude API vs subscription explains how API billing works. How to cut Claude Code and Codex costs covers what makes a plan's real limits last.

Why do I get 529 errors on Opus but not on Sonnet?

Capacity is tracked per model, so one model can be overloaded while another has room. That is why Claude Code suggests switching, for example from Opus to Sonnet, when one model is under high load.

Should I retry a 529 in my own code?

Yes, with exponential backoff and a cap. Anthropic's SDKs already retry 5xx errors twice by default; raise max_retries for batch jobs, and spread retries out over time. For work that can wait, the Message Batches API runs requests asynchronously and isn't subject to ramp limits.

Sources