Claude API Error 529 Overloaded: Causes and Fixes

A Claude API error 529 with type overloaded_error means Anthropic's API is temporarily at capacity across all users. It is not a problem with your key, your request body or your own rate limit. The right response is to retry with exponential backoff, and if it keeps happening, to fall back to another model or move work that can wait off the live path.

The details below are taken from Anthropic's official documentation (the Claude API errors page, the streaming guide, the SDK references and the Claude Code error reference), checked on 2026-09-24.

What Claude API error 529 overloaded means

Anthropic's errors page lists 529 as overloaded_error with a one-line description: the API is temporarily overloaded. The same page adds a warning that 529 errors can occur when the API experiences high traffic across all users.

That last clause is the whole diagnosis. A 529 describes the state of the service, not the state of your account. Nothing about your request made it happen, and nothing you change in the request will make it go away on the next attempt — only time, or sending the request somewhere with free capacity.

Like every Claude API error, the response body is JSON with a top-level error object that always carries a type and a message, plus a request_id:

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

Log the request_id every time. Anthropic's documentation asks for it when you contact support about a specific request, and it is the only reliable way to match a failure in your logs to a failure on their side.

529 vs 429 vs 500 vs 504: read the type, not just the number

These four are the ones that get confused, because all of them can look like "the API is not answering". They call for different responses:

Status	Error type	Whose side	What to do
429	`rate_limit_error`	Your organization hit a rate limit or a spend cap	Honor the `retry-after` header; if there is none, check whether it is a spend cap rather than a rate limit
500	`api_error`	Unexpected error inside Anthropic's systems	Retry with exponential backoff; contact support with the request ID if it persists
504	`timeout_error`	The request timed out while processing	Use streaming or the Message Batches API for long requests
529	`overloaded_error`	The API is at capacity across all users	Retry with backoff, then fall back

Two traps are worth knowing:

A capacity problem can arrive as a 429. Anthropic's errors and rate-limits pages both note that a sharp increase in your organization's usage can trigger 429 errors from acceleration limits. The fix there is on your side: ramp traffic up gradually and keep usage patterns consistent. If you are launching a batch job or a new feature, a 429 in the first minutes may be the ramp, not the steady-state limit. The Anthropic API rate limits guide covers how the three limits are measured.
A 429 without retry-after is not a throttle. Per the rate-limits documentation, the tier spend-cap 429 has no retry-after header and keeps failing until access resumes. Retrying it is wasted effort, and a retry loop that treats it like a 529 will spin forever.

If the error is a 400 rather than any of these, it is your request, not capacity — see Claude API error 400 causes and fixes.

Where a 529 shows up

The same condition surfaces in three different shapes, and code that only handles the first one will miss the other two.

As an HTTP status on a normal request. The request returns 529 and the body above. This is the easy case.

As an event inside a stream that already returned 200. Anthropic's streaming guide states that during periods of high usage you may receive an overloaded_error in the event stream, which would normally correspond to an HTTP 529 in a non-streaming context. It arrives as an event: error line with the same JSON shape. The errors page is explicit that when this happens after a 200, error handling does not follow the standard mechanisms — your HTTP status check has already passed. If you consume the raw stream yourself, you need a branch for error events, and you need to decide what to do with the partial output you already received. The Claude API streaming guide walks through the event types.

As "API Error: Repeated 529 Overloaded errors" in Claude Code. Claude Code's error reference says it has already retried several times before showing this message, and that a 529 is not your usage limit and does not count against your quota. Its recommended actions are to check status.claude.com, try again in a few minutes, or run /model and switch to a different model, because capacity is tracked per model.

What the official SDKs already do for you

Before writing your own retry loop, know what you get for free. According to the Python and TypeScript SDK references, the SDKs automatically retry certain errors two times by default with a short exponential backoff. Connection errors, 408, 409, 429 and all errors of 500 and above are retried — which includes 529. The Python SDK raises 529 as InternalServerError, the class it uses for every status of 500 or higher.

The retry count is configurable: max_retries in Python, maxRetries in TypeScript, on the client or per request. Setting it to 0 turns automatic retries off.

That default is a reasonable baseline for a chat request a user is waiting on. It is usually too short for a background job during a sustained capacity event, and it does nothing for errors that arrive mid-stream.

A retry policy that holds up under load

If you raise retries beyond the SDK default, do it in one place and do it deliberately. The pattern that works:

Exponential backoff with jitter. Double the wait each attempt and add randomness so thousands of clients that failed at the same moment do not all retry at the same moment.
A ceiling on each wait and on the total. Cap a single wait (for example 30 seconds) and cap the whole budget, so a request cannot hang for an unbounded time.
Retry only what is retryable. 529, 500 and connection errors yes; 400, 401, 403 and 404 never; 429 only after the retry-after interval, and not at all when that header is missing.
One retry layer, not two. If you add your own loop, set the SDK's retry count to 0, otherwise every one of your attempts becomes three.

import random
import time

import anthropic

client = anthropic.Anthropic(max_retries=0)  # this function owns retries

RETRYABLE = {500, 529}

def create_with_backoff(models, max_attempts=6, **kwargs):
    delay = 1.0
    for attempt in range(max_attempts):
        # stay on the first model for most attempts, move to the next one late
        model = models[min(attempt // 3, len(models) - 1)]
        try:
            return client.messages.create(model=model, **kwargs)
        except anthropic.APIStatusError as err:
            if err.status_code not in RETRYABLE or attempt == max_attempts - 1:
                raise
            time.sleep(delay + random.uniform(0, delay))
            delay = min(delay * 2, 30)

message = create_with_backoff(
    ["claude-sonnet-5", "claude-haiku-4-5"],
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarize this ticket."}],
)

The model list is the part most retry loops leave out. Retrying the same model during a capacity event assumes the event will end within your budget; switching models acts on the fact, stated in Claude Code's error reference, that capacity is tracked per model. Whether a smaller model is acceptable is a product decision — make it explicitly rather than letting a fallback silently change answer quality.

For streams, a mid-stream overloaded_error usually means discarding the partial output and re-sending the whole request, because the API gives you no way to resume a stream from where it stopped.

When retrying is not enough

If 529s are frequent rather than occasional, the fixes are architectural:

Check status.claude.com first. It is the official status page, and Claude Code points to it in its own 529 message. If there is an active capacity incident, the right move is to degrade gracefully and wait, not to tune retry parameters.
Take work that can wait off the live path. Nightly enrichment, evaluations and bulk classification belong in the Message Batches API, which Anthropic's service-tier documentation describes as the tier for asynchronous workflows that can wait or benefit from being outside your normal capacity. See Claude API batch processing for the constraints.
Stream long generations. Anthropic recommends the streaming Messages API or the Batches API for long-running requests, especially those over 10 minutes. This does not prevent 529s, but it stops long requests from compounding them with timeouts.
Know that Priority Tier is no longer on sale. Anthropic's service-tiers page says Priority Tier prioritizes requests to minimize "server overloaded" errors even at peak times, but capacity commitments are no longer available for purchase; organizations with an existing commitment keep it until their contract ends. For guaranteed capacity, the page directs you to Anthropic sales.

If you call Claude through a gateway or proxy

When your requests pass through an API gateway, relay or proxy, a 529 can originate in two places: Anthropic's API passed back to you, or the gateway's own capacity. What you see also depends on how the gateway maps errors — some pass the 529 and overloaded_error through unchanged, while an OpenAI-compatible layer may translate it into its own format.

Three checks keep this diagnosable:

Read the error type, not just the status code, and note which request ID you received — the gateway's, Anthropic's, or both.
Retry in one layer only. If the gateway already retries upstream 529s and your client also retries, a single overload becomes a multiplied burst of requests at exactly the moment capacity is short.
Compare against a direct call. If the gateway returns 529 while status.claude.com is clear and a direct request succeeds, the capacity problem is the gateway's.

The Claude API proxy guide covers what to verify in a gateway before you depend on it.

FAQ

Is a Claude API 529 error my fault?

No. Anthropic's errors page describes 529 as the API being temporarily overloaded, and says it can occur when the API experiences high traffic across all users. Your key, request body and rate limits are not the cause.

Should I retry a 529?

Yes, with exponential backoff and jitter. The official SDKs already retry 5xx errors twice by default; for background work you can raise that, and for persistent 529s add a fallback model.

Does a 529 count against my rate limit or quota?

Claude Code's error reference states that a 529 is not your usage limit and does not count against your quota. It is a capacity signal, distinct from the 429 you get when your own limits are reached.

What is the difference between a 529 and a 429?

A 429 means your organization hit a rate limit or spend cap and usually comes with a retry-after header. A 529 means the service is at capacity for everyone. The exception: a sharp spike in your own usage can trigger acceleration-limit 429s, which you fix by ramping traffic gradually.

Keeping multi-model access in one place

A per-model fallback only helps if switching models is cheap in your stack. ROIBest AI provides an OpenAI-compatible endpoint with one key across model families, so changing the model in a fallback is a parameter change rather than a new integration, and per-key usage records show which model actually served each request.