Claude API Error 529 (overloaded_error): What It Means and How to Fix It

An HTTP 529 from the Claude API comes with the error type overloaded_error. It means the API is temporarily overloaded, usually because of high traffic across all users, not because of anything wrong with your request or your account. The fix is almost always the same: wait briefly and retry with exponential backoff. The official SDKs already retry it for you by default.

This guide explains what 529 means, how it differs from 429 and 500, and how to handle it properly in production.

What the 529 error looks like

Every Claude API error comes back as JSON with an error object and a request ID:

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

The same ID is returned in the request-id response header. Log it. Anthropic support will ask for it if a problem persists.

529 vs 429 vs 500: which one are you seeing?

The key difference: a 429 is about your usage, and a 529 is about overall load. Raising your rate limits won’t prevent 529s. One nuance from Anthropic’s documentation: a sharp jump in your own traffic can also trigger 429s from acceleration limits, so ramp new workloads up gradually.

One kind of 429 should not be retried automatically. If you’ve reached a monthly spend cap, the response has no retry-after header and will keep failing until access resumes or the cap is raised.

How to fix and prevent 529 errors

1. Let the SDK retry, and tune it

The official Python and TypeScript SDKs automatically retry connection errors, rate limits and 5xx errors, including 529, with exponential backoff. They retry twice by default and honour retry-after when it’s present. For batch jobs or background workers, raise the retry count:

import anthropic

client = anthropic.Anthropic(max_retries=5)  # default is 2

In TypeScript, pass maxRetries when you create the client. You can also override it per request.

2. If you call the API directly, add backoff with jitter

Without an SDK, retry 529, 500 and 504 with increasing waits plus a little randomness, so many clients don’t all retry at the same instant:

import random, time, requests

def call_with_backoff(payload, headers, max_attempts=6):
    for attempt in range(max_attempts):
        r = requests.post("https://api.anthropic.com/v1/messages", json=payload, headers=headers, timeout=600)
        if r.status_code not in (429, 500, 504, 529):
            return r
        retry_after = r.headers.get("retry-after")
        wait = float(retry_after) if retry_after else min(60, 2 ** attempt) + random.random()
        time.sleep(wait)
    r.raise_for_status()

3. Don’t turn a spike into a storm

• Cap concurrency. Use a queue or semaphore, rather than firing hundreds of requests at once.
• Ramp traffic up gradually when you launch a new feature or batch job.
• Use a circuit breaker. After several consecutive 529s, pause briefly before trying again, instead of retrying every request immediately.

4. Move work that isn’t urgent to the Message Batches API

For large jobs that don’t need an instant answer, such as classification, summarising a backlog or evaluations, the Message Batches API queues the work and you poll for results. You don’t hold thousands of live requests open during busy periods.

5. Use streaming for long responses

Anthropic recommends the streaming Messages API, or batches, for requests that may run longer than about 10 minutes. Long, non-streaming requests are more likely to be dropped by networks that close idle connections. With streaming, note that an error can arrive after a 200 response has started, as an error event in the stream, so handle it there too.

6. Plan a fallback for user-facing features

If a feature must respond even during an overload, decide in advance what happens after retries run out. You might fall back to a different Claude model, return a cached or simpler answer, or show a clear “try again in a moment” message, rather than a raw error.

7. Check the status page

If 529s are widespread, check status.claude.com. Incidents and elevated error rates are posted there. If everything looks normal but your errors continue, contact support with your request IDs.

Quick checklist

• Retries enabled, with exponential backoff and jitter
• retry-after honoured on 429s
• Concurrency capped, and new traffic ramped gradually
• Long outputs streamed. Bulk work sent through the Batches API
• Request IDs logged for every failed call
• A fallback for user-facing paths when retries are exhausted