Claude Overloaded Error (529): Is Claude Down? What to Do

One-sentence answer: Overloaded (529 / overloaded_error) means Anthropic's servers are temporarily at capacity across all users—it is not a problem with your settings or usage limit, does not count against your quota, and usually recovers within a few minutes.

What to Do Right Now

1. Wait 1–5 minutes and try again (do not rapid-fire retry): In Claude Code, the client has already retried several times automatically before displaying the error, so hammering retry immediately will not help.
2. Switch models with /model in Claude Code: Capacity is tracked per model. If Opus is overloaded, run /model to switch to Sonnet (or pass claude --fallback-model sonnet,haiku).
3. If overload persists, route through UniRoute: Jump to the UniRoute setup section below to route requests to the most stable available regional capacity and automatically retry pre-stream 529 errors across upstream accounts.

---

1. Using Claude.ai Web or Desktop App

When a specific model (such as Claude Opus) experiences heavy global traffic in the web interface or desktop app, the Claude Code error reference notes that the desktop app displays:

Opus is experiencing high load. Switch to Sonnet.

How to recover on Web / Desktop:

1. Check the live status box above (or https://status.claude.com) to see whether claude.ai has an active incident.
2. Switch the model selector in your chat from Opus to Sonnet—because capacity is tracked per model, Sonnet often remains responsive while Opus is at capacity.
3. Wait 1–5 minutes before resending your prompt instead of clicking retry repeatedly.

---

2. Using Claude Code

According to the Claude Code error documentation, when the API is temporarily at capacity across all users, Claude Code automatically retries several times before printing:

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 Claude Opus specifically is under high load, the CLI prompts:

Opus is experiencing high load, please use /model to switch to Sonnet

Official steps for Claude Code users:

1. Check https://status.claude.com (or the live status widget above).
2. Wait a few minutes and try again: An HTTP 529 is not your organization's usage limit and does not count against your quota.
3. Switch models with /model: Because capacity is tracked per model, run /model in your interactive session to switch to Sonnet (or use claude --fallback-model sonnet,haiku for non-interactive runs). If official capacity remains overloaded, connect Claude Code to UniRoute.

---

3. Using the Claude API (For Developers)

When Anthropic's API experiences high traffic across all users for a model, it returns HTTP 529 with error type overloaded_error (described as "The API is temporarily overloaded." in the Anthropic API errors reference; the error.message text can vary).

3.1 Exact HTTP 529 & overloaded_error Messages Across the API, Claude Code, and Gateways

Because an overload can occur before HTTP headers are sent, after an initial HTTP 200 stream starts, or behind an inference gateway, the exact error message tells you where the failure surfaced.

A. Direct Anthropic Messages API (POST /v1/messages)

When a request is rejected due to high traffic across all users, Anthropic returns HTTP status 529 with a request-id response header and the documented overloaded_error JSON error shape (not a captured live response; the error.message text can vary, and "req_..." is a placeholder):

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

B. Claude Code CLI (Documented Messages vs Print Mode With a Custom Base URL)

Claude Code retries 529 with exponential backoff before printing an error:

• Documented Claude Code error after repeated 529s:

  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.
  

• Documented model-specific load prompt (when Claude Opus is under high load):

  Opus is experiencing high load, please use /model to switch to Sonnet
  

• Print mode (claude -p) with a custom ANTHROPIC_BASE_URL (observed in our local mock test with Claude Code 2.1.295 when the upstream returned HTTP 529 with "message": "Overloaded"):

  API Error: 529 Overloaded. This is a server-side issue, usually temporary — try again in a moment. If it persists, check your inference gateway (127.0.0.1:<port>).
  

C. Mid-Stream SSE Error After HTTP 200 OK

As documented in Anthropic's streaming error events guide, when streaming is enabled ("stream": true), an error can occur after the initial HTTP 200 response has already started and arrive as a Server-Sent Events (SSE) error event.

In Claude Code (v2.1.199+), a server error that interrupts a response mid-stream surfaces as:

API Error: Server error mid-response. The response above may be incomplete.

D. Behind UniRoute Gateway (HTTP 503 After All Upstream Attempts Are Exhausted)

When requests run through UniRoute (disclosure: our own gateway) and an upstream account returns 529 before streaming begins, UniRoute can pause that account for a cooldown period (the cooldown is configurable; production setting not checked) and try another upstream account for the same model. Only if every pre-stream upstream attempt is used up does UniRoute return HTTP 503:

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "Upstream service overloaded, please retry later"
  }
}

In claude -p pointed at a custom base URL returning that 503 payload, Claude Code prints:

API Error: 503 Upstream service overloaded, please retry later. This is a server-side issue, usually temporary — try again in a moment. If it persists, check your inference gateway (127.0.0.1:<port>).

3.2 Diagnostic Table: 529 vs 429 vs 400 vs 500 vs 504 vs 503

Before changing retry settings, check the HTTP status code and error type to confirm whether you are hitting shared model traffic (529) or an organization limit (429/400):

3.3 How Claude Code Retries 529 and When --fallback-model Switches

How We Tested

On 2026-10-18, we ran Claude Code 2.1.295 (darwin arm64) in print mode (claude -p "reply OK") against a local mock HTTP server on 127.0.0.1 returning HTTP 529 ({"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}) and HTTP 503 ({"type":"error","error":{"type":"overloaded_error","message":"Upstream service overloaded, please retry later"}}). This test made no real API calls and cost $0. It measures how the Claude Code 2.1.295 client binary schedules retries and model fallbacks; it does not reproduce a live Anthropic 529 incident or measure live production frequency.

Observed Retry & Fallback Results (Claude Code 2.1.295, 2026-10-18)

What This Means When Using --fallback-model

In our test with Claude Code 2.1.295, the switch to the fallback model happened after 3 consecutive 529 responses on the primary model, and when only 1 retry was allowed (CLAUDE_CODE_MAX_RETRIES=1) it never switched. If you rely on a fallback model, setting a very low retry count can end the request before the switch occurs—in our test, 1 retry was too few.

3.4 Configuring Claude Code Retry & Fallback Settings

A. Tune Retry Count and 529 Backoff Delays

Claude Code provides environment variables to adjust retry counts and 529 exponential backoff timing:

# Default is 10 retries (capped at 15 in v2.1.186+).
# If you rely on a fallback model, avoid setting this too low (1 retry was too few to switch in our test).
export CLAUDE_CODE_MAX_RETRIES=5

# Base delay for 529 overloaded exponential backoff (default: 500ms, max: 32000ms, v2.1.292+)
export CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS=1000

# Maximum per-retry delay cap for 529 backoff (default: 32000ms, max: 64000ms, v2.1.296+)
export CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS=32000

B. Unattended Runs (CLAUDE_CODE_RETRY_WATCHDOG)

For unattended claude -p tasks, you can enable CLAUDE_CODE_RETRY_WATCHDOG:

export CLAUDE_CODE_RETRY_WATCHDOG=1
# Optional (v2.1.295+): maximum time in milliseconds that each API request spends waiting out 429/529
export CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=300000

claude -p --fallback-model sonnet,haiku "Run the test suite and summarize failures"

When CLAUDE_CODE_RETRY_WATCHDOG=1 is set, Claude Code retries 429 and 529 capacity errors indefinitely instead of failing after CLAUDE_CODE_MAX_RETRIES attempts (and in v2.1.199+, raises default retries for other transient errors to 300), while still failing immediately on spend-limit 429 responses (v2.1.239+). In v2.1.295+, CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS caps the maximum time each API request spends waiting out 429/529.

C. Configure fallbackModel in .claude/settings.json or CLI

In non-interactive mode (claude -p), you can pass a fallback chain on the command line:

claude -p --fallback-model sonnet,haiku "Summarize recent commits"

Or configure "fallbackModel" in .claude/settings.json using the documented format:

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

Per the Claude Code documentation, a fallback switch lasts for the current turn, fallback chains are capped at three models, and the --fallback-model CLI flag overrides the fallbackModel setting when both are present.

3.5 Official Anthropic SDK Retry Behavior (TypeScript & Python)

If you call the API through the official @anthropic-ai/sdk (TypeScript) or anthropic (Python) SDKs, the client retries connection errors, rate limits, and 5xx server errors with exponential backoff, twice by default, honoring retry-after headers.

The example below uses the same base URL as the Claude Code setup guide (https://api.uniroute.app); we did not test the SDK path in this article. The environment variable name you use to store your API key is your own choice:

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.MY_API_KEY, // env var name is your own choice
  baseURL: 'https://api.uniroute.app',
  maxRetries: 4, // Default is 2
});

And in Python:

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["MY_API_KEY"],  # env var name is your own choice
    base_url="https://api.uniroute.app",
    max_retries=4,  # Default is 2
)

Avoid wrapping SDK calls in a second outer retry loop when maxRetries is already enabled on the client, as nested loops multiply upstream attempts during an overload.

---

4. Route Claude Code or the API Through UniRoute When Overload Persists

Disclosure: UniRoute is our own unified AI API gateway. Routing through UniRoute does not guarantee zero overloads or prevent mid-stream errors after a response has already started.

Official Claude 529 overloads depend on aggregate load across global servers. When you connect Claude Code or the Anthropic SDK to UniRoute, UniRoute routes requests across regions to the most stable available capacity while keeping the same Claude model ID:

1. Pre-stream account failover: If nothing has been streamed to your client yet when an upstream account returns 529, UniRoute can pause that account for a cooldown period (the cooldown is configurable; production setting not checked) and retry on another upstream account for the same model.
2. When every upstream attempt is used up: Only if all pre-stream upstream attempts for your request are exhausted does UniRoute return HTTP 503 with error.type: "overloaded_error" and "Upstream service overloaded, please retry later".
3. After streaming starts: Once the HTTP 200 stream has started sending data to your client, UniRoute cannot switch upstream accounts or replay the request mid-response.

Pricing & channel failover: As of 2026-10-27, on UniRoute's discounted channel Anthropic Claude models are as low as 42% of official API rates (for example, Claude Sonnet 5.5 at $0.84 / $4.20 per 1M input/output tokens vs $2.00 / $10.00 official, and Claude Opus 5.5 at $1.68 / $8.40 vs $4.00 / $20.00 on UniRoute Pricing); when the discounted channel is unavailable, requests fail over automatically to the standard channel at official-level prices (how channels work).

Configure Claude Code with uniroute-setup

First create an API key in the UniRoute console, then run in your terminal (requires Node.js 22+; prompts for your key without echoing it):

npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup models
npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup configure claude --model MODEL_ID --dry-run
npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup configure claude --model MODEL_ID

See the full Claude Code CLI setup guide for manual .claude/settings.json configuration and verification steps.

---

5. Pre-Retry Checklist: Status Page & Usage Records

Before re-running an interrupted Claude Code command:

1. Check https://status.claude.com: Anthropic's status page tracks claude.ai, Claude Console (platform.claude.com), Claude API (api.anthropic.com), and Claude Code separately.
2. Inspect your local workspace after a mid-response error: If Claude Code printed API Error: Server error mid-response. The response above may be incomplete., check git status and git diff to see which file edits or commands already ran.
3. Check your usage records before resending: Check the request in your UniRoute usage records before sending a duplicate request, and see our Claude Code API Error 500 guide for the step-by-step support-report checklist (including saving the request-id privately).

---

6. Frequently Asked Questions (FAQ)

1. Does an HTTP 529 error use my quota or cost money?

No. According to the Claude Code error documentation, a 529 is not your usage limit and doesn't count against your quota—it indicates high traffic across all users on the API. If a request failed mid-stream after returning HTTP 200, check your usage records before resending.

2. How long does a 529 overload last?

Anthropic does not publish a fixed duration for 529 capacity spikes; the error message notes that it is "usually temporary" and advises trying again in a moment or checking https://status.claude.com if it persists. Switching models (/model or --fallback-model) can help because capacity is tracked per model.

3. Is HTTP 529 caused by my organization's rate limit?

No. Organization rate limits, traffic acceleration limits, and monthly tier spend caps return HTTP 429 (rate_limit_error), and user-configured spend limits return HTTP 400 (invalid_request_error). HTTP 529 (overloaded_error) is caused by high traffic across all users.

4. Why does Claude Code say "check your inference gateway"?

When ANTHROPIC_BASE_URL is configured to point to a custom gateway or local proxy instead of Anthropic's default endpoint, Claude Code's print-mode error message includes If it persists, check your inference gateway (<host>) so you know which upstream endpoint returned the 529 or 503 response.

5. Is "overloaded" the same as "Claude is down"?

Not necessarily. Capacity is tracked per model, so another model such as Sonnet may still have capacity (Claude Code suggests switching with /model), and https://status.claude.com tracks claude.ai, Claude Console (platform.claude.com), Claude API (api.anthropic.com), and Claude Code as separate components.