API error: 529 from Anthropic: what overloaded_error means and how to survive it

API error: 529, and what the body actually says

The Claude API returns a small, fixed set of error types, and 529 is the one that means the service itself is short of capacity. Anthropic describes it on the errors page in five words: the API is temporarily overloaded.

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "Overloaded"
  },
  "request_id": "req_011CcLPBRWGbL1Spc2GsDen6"
}

It helps to see 529 in the context of the whole family, because several of these get confused with each other and only two of them are worth retrying blind.

How 529 differs from 429, in Anthropic's own words

This is the distinction the whole page turns on, and Anthropic states it explicitly in a warning attached to the 529 row:

So the two errors point at opposite halves of the system, and the useful consequence is that they have different fixes and different time horizons.

A quick field test: if every key in your organization fails at the same moment and a completely unrelated project on a different account fails too, that is a 529. If only your busiest worker pool fails while a manual curl succeeds, that is a 429 and you are shaping your own traffic badly.

The retry that actually works

Start by checking that you have not turned off the behaviour you already had. The official SDKs handle this class of error out of the box:

529 falls inside that >=500 bucket, so it is already retried, and retry-after is already honoured. The most common reason a team sees raw 529s reaching application code is that somebody set max_retries=0 to make latency predictable and never revisited it.

from anthropic import Anthropic

# interactive path: fail fast, let the UI offer a retry
fast = Anthropic(max_retries=1, timeout=30.0)

# background path: absorb an incident instead of paging someone
patient = Anthropic(max_retries=6)

When you are writing the loop yourself

Anthropic recommends exponential backoff in the docs. It does not mention jitter anywhere, so treat the jitter part as general distributed-systems practice rather than a vendor instruction. It matters more than the backoff itself: a fleet of workers that all back off on an identical schedule reconverges into a synchronized second wave, which is exactly what the overloaded service does not need.

import random, time
import anthropic

BASE, CAP, MAX_ATTEMPTS = 1.0, 32.0, 6

def call_with_retry(client, **kwargs):
    for attempt in range(MAX_ATTEMPTS):
        try:
            return client.messages.create(**kwargs)
        except anthropic.APIStatusError as err:
            # 529 and 5xx are capacity. 4xx other than 429 will never succeed.
            if err.status_code not in (429, 500, 502, 503, 504, 529):
                raise
            if attempt == MAX_ATTEMPTS - 1:
                raise
            # the server's own number wins whenever it gives one
            hinted = err.response.headers.get("retry-after")
            if hinted:
                delay = float(hinted)
            else:
                delay = random.uniform(0, min(CAP, BASE * (2 ** attempt)))
            time.sleep(delay)

Six attempts buys you about half a minute of patience, which covers the ordinary blip. It does not cover an incident, and no retry schedule does. Somewhere around 60 to 120 seconds of continuous 529s, retrying stops being a fix and starts being a way to keep a user staring at a spinner.

The 529 that arrives as an HTTP 200

This one bites agent frameworks in particular, and it is worth knowing before it happens to you. Anthropic is explicit that streaming breaks the normal error contract:

In practice, capacity can run out after the connection is established and the first tokens are already on the wire. What you get is a well-formed 200, a partial response, and then an error event in the stream carrying the same overloaded_error body. Any handler that keys on response.status_code sees success, and any agent loop that treats a truncated turn as a finished turn will happily commit half an answer.

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Sure, I can"}}

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

• Handle the error event explicitly. The SDK stream helpers raise on it; a hand-rolled SSE reader usually does not.
• Treat a stream that ends without message_stop as a failure, not as a short answer.
• Do not retry a partial turn by appending to it. Discard the fragment and resend the original request, or you will end up prefixing the assistant turn with whitespace and collecting a 400 as well.

Check the status page before you change anything

status.anthropic.com redirects to status.claude.com, which reports the API separately from claude.ai, the Console, and Claude Code. That separation matters: the web app can be fine while api.anthropic.com is degraded, and a working browser session tells you nothing about your integration.

It is worth being honest about how often this is real rather than something you did. Checked on 19 August 2026, the incident history for that month alone lists degraded performance or elevated errors on the 5th, 12th, 13th, 14th, 15th, 16th, 17th, 18th, and 19th, several of them naming specific models. Trailing 90-day uptime for the Claude API showed 99.46%. That is a good service, and it is also several hours a quarter where a 529 is the correct and expected response.

curl -sS -D /tmp/h -o /tmp/b https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

grep -i '^request-id' /tmp/h

When retrying stops working: failover

Every retry policy needs an exit. A 529 is the clearest case in the whole error taxonomy for having a second path, because the failure is provider-wide and time-unbounded: no amount of patience on your side changes the queue you are in.

There are three exits, in ascending order of effort.

1. A second model on the same provider. Overload is often model-specific. The status incidents in August 2026 repeatedly named individual models rather than the whole API, so a fallback from a flagship to a smaller model frequently succeeds while the first one is still failing. This is the cheapest failover to build and it needs no new credential.
2. A second route to the same model. Claude is served on the first-party API, Amazon Bedrock, Google Cloud, and Microsoft Foundry. Capacity pools differ. This costs you a second set of credentials and a small abstraction over request shapes, and it is the only option that preserves exact model behaviour.
3. A different provider entirely. The most robust and the most work, because output shape, tool-calling conventions, and prompt sensitivity all shift. Worth it for anything where an outage is expensive; overkill for a nightly batch that can simply run an hour later.

Questions people ask

Keep reading

Continue through Errors and fixes with API error: 400 messages: text content blocks must be non-empty.