Anthropic 529 overloaded_error: what it means and how to handle it

The Claude API returns 529 with the error type overloaded_error when the API is temporarily overloaded. According to Anthropic, it can happen when the API experiences high traffic across all users. Your request is fine. The API is busy, so it turned the request down. When your organization goes over its own rate limits, you get a 429 instead. The response body has the same shape as every other Claude API error: a top-level type of error, an error object with type and message, and a request_id you can give to Anthropic support. For more information, see Claude API errors.

529, 429, or spend cap: how to tell them apart

The Claude API uses similar-looking errors for very different problems. Some go away if you wait. One doesn't go away until next month.

A spend-cap 429 has the same error type as a rate limit, so code that retries every rate_limit_error keeps failing. Anthropic notes that retries fail until access resumes, including the SDK's automatic retries. For details, see Reaching your spend cap.

How to handle a 529

1. Check the status code before you retry. A 529 and a 429 need different waits, and a 429 without retry-after needs no retry at all.
2. Back off on a 529. Retry with exponential backoff and random jitter, and stop after a few attempts. If the response has a retry-after header, wait that long instead.
3. Let the SDK do the first retries. The official Anthropic SDKs retry connection errors, rate limits, and 5xx errors twice by default, with exponential backoff, and honor retry-after when it's present. You can change the count with max_retries (maxRetries in TypeScript). When the SDK runs out of retries, your code gets the error.
4. Stop retrying on a spend cap. If a 429 has no retry-after header, tell the user and alert yourself.
5. Keep the user informed. Queue the work and try again later, or show a clear "busy, try again in a minute" message instead of a generic error.

In the Python SDK, a 429 raises anthropic.RateLimitError and any status of 500 or above, including 529, raises anthropic.InternalServerError:

import anthropic

client = anthropic.Anthropic(max_retries=4)


def summarize(text: str) -> str | None:
    try:
        message = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": f"Summarize:\n\n{text}"}],
        )
    except anthropic.RateLimitError as e:
        if "retry-after" not in e.response.headers:
            # Spend cap: every retry fails until access resumes
            alert_admin(e)
            return None
        raise
    except anthropic.InternalServerError as e:
        if e.status_code == 529:
            # Overloaded after all SDK retries: queue the job for later
            queue_for_later(text)
            return None
        raise
    return next(block.text for block in message.content if block.type == "text")

How to test that your app handles a 529

You rarely see a 529 while you develop. It depends on traffic from every Claude API user, so you can't trigger it. The way you test decides whether you find the bugs before your users do.

Try it on your app

Dev Proxy intercepts your app's requests to https://api.anthropic.com and returns errors in Anthropic's error format, while your app keeps calling the real URL. Download a preset, and start Dev Proxy with it:

devproxy config get anthropic-throttling
devproxy --config-file "~dataFolder/configs/anthropic-throttling/.devproxy/devproxyrc.json"

Neither preset includes a spend-cap 429. To test that path, add a response without a retry-after header to the preset's anthropic-errors.json file:

{
  "statusCode": 429,
  "headers": [
    { "name": "content-type", "value": "application/json" }
  ],
  "body": {
    "type": "error",
    "error": {
      "type": "rate_limit_error",
      "message": "You have reached your API usage limits.",
      "details": { "error_code": "enforced_spend_limit_reached" }
    }
  }
}

To make every request fail, so that you see what happens when the SDK runs out of retries, start Dev Proxy with --failure-rate 100. For more information, see Change request failure rate. To install Dev Proxy, see Set up Dev Proxy.

Next steps

See also

• 429 Too Many Requests: what it means and how to handle it
• 500, 502, 503, and 504 errors from APIs: what they mean and how to handle them
• What is throttling?
• Test that my application handles throttling properly