Claude API "529 overloaded_error" (Overloaded): What It Means and What to Do

Short answer

HTTP 529 with "type": "overloaded_error" means the Claude API is temporarily overloaded. Anthropic's error reference says 529 errors can occur when the API experiences high traffic across all users. It isn't your rate limit, your spend limit or your Claude subscription quota, so nothing on your account needs changing.

What helps:

• Retry with backoff. The official SDKs already retry 5xx errors twice by default. Raise the retry count for jobs that can wait.
• Check status.claude.com for a capacity notice.
• Switch to another model. In Claude Code, run /model. Claude Code's docs say capacity is tracked per model, so a different model often keeps working while one is overloaded.
• Set a fallback so this happens on its own next time: fallbackModel in Claude Code, or a second model in your own retry code.

What the error looks like

In the API. The error body is the standard Claude error object. During streaming, the same error can arrive as an event after the request already returned 200. This is the example from Anthropic's streaming docs:

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

A non-streaming request gets HTTP 529 with the same error object, plus a request_id.

In Claude Code. Claude Code retries first and only shows the error when the retries run out. The Claude Code error reference gives this message:

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.

When one model is under particularly high load, Claude Code may suggest a switch instead, for example Opus is experiencing high load, please use /model to switch to Sonnet. If you use Claude Code through a gateway or a cloud provider, the last sentence names that provider or gateway host instead of status.claude.com, and that's the status page to check.

529 vs. 429, 500 and usage limits

These look alike in logs but have different fixes:

Two details from Anthropic's docs:

• A 529 doesn't count against your quota. The Claude Code error reference says so explicitly.
• A sharp increase in your own traffic can cause 429 errors, not 529s, because of acceleration limits. Anthropic suggests ramping up gradually. If you only see errors right after a traffic jump, look at the 429 side first. Our Claude Code limits guide covers rate limits.

Fixing it in your own code

1. Let the SDK retry, and give it more room. The official SDKs retry connection errors, rate limits and 5xx errors with exponential backoff, twice by default. Set max_retries higher for batch jobs.
2. Catch the overload error by its type. The Python SDK raises anthropic.OverloadedError for a 529. Catch the typed exception rather than matching the message text.
3. Fall back to a second model. If retries on one model keep failing, try the request on another model.
4. Handle errors inside streams. A 200 response doesn't mean the stream finishes. Treat an error event with overloaded_error the same as a 529 and retry the request.
5. Log the request ID. Every response carries a request-id header. Include it if you contact Anthropic support.

import anthropic

client = anthropic.Anthropic(max_retries=5)

MODELS = ["claude-sonnet-5", "claude-haiku-4-5"]  # primary first, then fallback


def ask(prompt: str):
    last_error = None
    for model in MODELS:
        try:
            return client.messages.create(
                model=model,
                max_tokens=1024,
                messages=[{"role": "user", "content": prompt}],
            )
        except anthropic.OverloadedError as e:  # HTTP 529
            last_error = e  # retries on this model are used up; try the next one
    raise last_error

Fixing it in Claude Code

Claude Code retries transient failures, including overloaded responses, up to 10 times with exponential backoff before it shows the error. By the time you see the message, waiting a little longer is still the main fix. These settings help:

• Switch models. Run /model and pick another model. In the Claude Desktop app's Code tab or Cowork, use the model picker.
• Set a fallback chain. Claude Code can switch to a fallback model when the primary one is overloaded or unavailable, for that turn only:

claude --fallback-model sonnet,haiku

To keep it for every session, set fallbackModel in your settings:

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

Fallback chains don't switch on authentication, billing or rate-limit errors, only on overloaded, unavailable and other non-retryable server errors (model configuration).

• Keep unattended runs alive. For CI jobs or long autonomous runs, set CLAUDE_CODE_RETRY_WATCHDOG=1. Claude Code then retries 429 and 529 capacity errors indefinitely instead of giving up after CLAUDE_CODE_MAX_RETRIES attempts (default 10).
• Spread retries out. On v2.1.292 or later, CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS (default 500, up to 32000) sets the starting delay between 529 retries.

Using Claude through TeamoRouter

Another endpoint doesn't give an overloaded model more capacity, and we don't promise that you'll never see a 529 through TeamoRouter. What it gives you is one pay-per-use account for several model families.

TeamoRouter is an API gateway with one key for Claude, GPT, Gemini and DeepSeek. Claude runs on the native Anthropic protocol (/v1/messages), and GPT and the other models are available through the OpenAI-compatible /v1/chat/completions. When switching Claude models isn't enough, moving a task to another family is a change of model name, not a new account. There's no subscription; you pay per use.

1. Create an API key in the TeamoRouter console. It starts with sk-teamo-.
2. Top up from $5. The top-up dialog takes cards. You can also click Pay with crypto and pay with USDT, USDC or ETH from Binance, OKX or any exchange app — the checkout shows which networks your amount supports (BEP20 works from $5). You don't need a wallet extension. Step by step: Pay for Claude with USDT.
3. Point Claude Code at it (macOS and Linux):

export ANTHROPIC_BASE_URL=https://api.teamorouter.com
export ANTHROPIC_AUTH_TOKEN="your TeamoRouter API key"
claude

Leave /v1 off the base URL. For the Anthropic SDK, pass base_url="https://api.teamorouter.com" and your TeamoRouter key. GET /v1/models lists the model IDs you can use. Windows commands and model settings are in Install and connect Claude Code, and every protocol is in the API integration guide.

FAQ

Does a 529 count against my rate limit or my Claude plan? No. Anthropic's Claude Code docs say a 529 is not your usage limit and doesn't count against your quota.

How long does an overload last? The error reference doesn't give a typical duration; Claude Code's message only says it is usually temporary. Check status.claude.com for active incidents, retry with backoff, or switch models in the meantime.

Why do I get 529 on one model but not another? Claude Code's error reference says capacity is tracked per model. That's why /model and fallback chains are the recommended workaround.

Will upgrading my plan or usage tier stop 529 errors? Anthropic's docs describe 529 as high traffic across all users, not as a limit on your account. Higher tiers raise your rate limits, which is a 429 problem.

Next steps

• Claude Code limits and quota management
• Claude Code "Prompt is too long": how to fix it
• Install and connect Claude Code
• Pay for Claude and GPT APIs with USDT