Claude API Error 529 Overloaded: Configure Retries and Reduce Pressure

Claude API error 529 means the API is temporarily overloaded. When the response contains 529 and overloaded_error, keep the request details, check the service's status, and retry only within a defined budget. If you control the application, reduce concurrent calls and pause non-urgent work while capacity is constrained. Changing an API key or buying more quota is not the first fix for this response. Anthropic defines the error in its API error reference.

Before adding a retry loop, count what already retries: the SDK, your application, and any gateway. Choose one place to schedule attempts. The Python settings and example below let you either keep SDK-managed retries or give your application control over a short retry window, including when to stop.

If all you see is send failed: overloaded, obtain the underlying status and error body before treating it as a confirmed 529. That wording may come from a wrapper. If it appears in a Claude Code session, use the Claude Code 500 and 529 recovery guide to retain the conversation and inspect completed actions.

Confirm which response you actually received

A returned HTTP error gives you a more useful starting point than the final line of a log. Capture the status, error.type, error.message, timestamp, and request ID when available. For a gateway, also record which host answered; its outward-facing error may differ from an upstream Anthropic response.

The returned-error definitions and the spend-cap distinction come from the current API reference. A 529 does not establish that every model or provider is unavailable, and it does not establish the billing rules of a custom gateway.

Check Claude Status for the relevant service and record the time. For a cloud provider or gateway, check that service too. An incident can explain failures and make deferring work the sensible action. A green status page is useful context, but your application's result on the failing model and endpoint remains the recovery check. If you cannot identify which product produced the message, start with the Claude error and service-status guide.

Set the Python SDK retry policy before adding a loop

The Python SDK documentation specifies two automatic retries by default for eligible failures, including connection errors, 408, 409, 429, and statuses of 500 or higher. That means an initial attempt plus up to two retries, rather than two total attempts. Response conditions can stop the SDK earlier.

Use max_retries on the client or client.with_options(...) for a particular call. Pick the arrangement that matches your application:

For example, three outer calls with the documented two SDK retries can produce up to nine HTTP attempts: 3 × (2 + 1). This is a calculation for eligible failures with those settings, not measured traffic or a universal count. A gateway can add further attempts, while early stops can reduce them.

The SDK's documented default request timeout is 10 minutes. A timeout can also be retried twice by default. Set timeout to suit the expected request duration, but keep it separate from the application's overall deadline: retries, waiting, queue time, and transport timeout semantics can all affect elapsed time. timeout=20.0 does not promise that the whole user request finishes within 20 seconds. Source: SDK retries and timeouts.

Catch 529 by status rather than assuming an exception subclass

For version-compatible handling, catch anthropic.APIStatusError and inspect exc.status_code == 529. The SDK guide documents this interface. In the Python SDK's main source inspected on October 4, 2026, 529 maps to OverloadedError, which inherits directly from APIStatusError, independently of InternalServerError. That source snapshot does not establish which class your installed release raises. A catch limited to InternalServerError can therefore be too narrow. Sources: SDK interface, status mapping, exception definitions.

A bounded 529 retry window you can adapt

For an application-owned policy, disable SDK retries, limit the number of attempts, and stop scheduling new ones once the retry window expires. If a server asks you to wait longer than the remaining window, end this request rather than shorten the wait and retry early. A background worker may defer a still-valid job; an expired chat turn should return a temporary-unavailable result.

The following synchronous Python helper handles returned 529 responses only. It requires the anthropic package in your application's environment, an already configured Anthropic client, an enabled model ID, and a Messages API input. It performs no tool execution or stream replay. Other HTTP errors, connection failures, and SDK timeouts propagate to the caller for their own handling.

import math
import random
import time
from datetime import timezone
from email.utils import parsedate_to_datetime

import anthropic


def server_wait_seconds(headers):
    """Read milliseconds, seconds, or an HTTP-date when supplied."""
    for name, divisor in (("retry-after-ms", 1000.0), ("retry-after", 1.0)):
        raw = headers.get(name)
        if raw is None:
            continue
        try:
            value = float(raw) / divisor
        except (TypeError, ValueError):
            continue
        if math.isfinite(value):
            return value
    raw = headers.get("retry-after")
    if raw is not None:
        try:
            date = parsedate_to_datetime(raw)
            if date.tzinfo is None:
                date = date.replace(tzinfo=timezone.utc)
            return date.timestamp() - time.time()
        except (TypeError, ValueError, OverflowError):
            pass
    return None


def generate_with_529_budget(
    client, *, model, messages, max_tokens=512,
    max_attempts=3, retry_window=30.0, attempt_timeout=20.0,
):
    if max_attempts < 1 or retry_window <= 0 or attempt_timeout <= 0:
        raise ValueError("Use a positive attempt count and time settings")
    expires_at = time.monotonic() + retry_window
    last_error = None

    for attempt in range(max_attempts):
        remaining = expires_at - time.monotonic()
        if remaining <= 0:
            raise TimeoutError("529 retry window expired") from last_error
        try:
            return client.with_options(
                max_retries=0,
                timeout=min(attempt_timeout, remaining),
            ).messages.create(
                model=model, max_tokens=max_tokens, messages=messages,
            )
        except anthropic.APIStatusError as exc:
            last_error = exc
            headers = exc.response.headers
            if exc.status_code != 529:
                raise
            if headers.get("x-should-retry", "").lower() == "false":
                raise
            if attempt + 1 == max_attempts:
                raise  # No sleep after the final failed attempt.

            server_wait = server_wait_seconds(headers)
            if server_wait is not None and server_wait > 0:
                delay = server_wait
            else:
                delay = random.uniform(0.5, 1.0) * min(8.0, 2.0 ** attempt)
            remaining = expires_at - time.monotonic()
            if delay >= remaining:
                raise TimeoutError("No retry fits the remaining window") from exc
            time.sleep(delay)

Call the helper from your existing integration, passing its client, configured model, and messages. With these example defaults, it schedules at most three attempts during a 30-second retry window, uses no internal SDK retries, and requests an attempt timeout of at most 20 seconds. These are illustrative application settings, not Anthropic-recommended universal values. A quick interactive request and a long background analysis need different settings.

The retry window controls whether another attempt starts; it is not a hard end-to-end deadline. The time check occurs before each call, and the transport's timeout does not guarantee a wall-clock cutoff. A call can finish after the window. If your service promises a hard deadline, enforce cancellation through your runtime and HTTP integration, include queue time in that deadline, and check whether the request is still valid before delivering a late result. Client cancellation also does not establish that remote work was undone.

The header parser gives retry-after-ms priority, then accepts numeric retry-after or an HTTP date. The helper also preserves an explicit x-should-retry: false. These reflect behavior in the Python SDK main implementation inspected on October 4, 2026. In that snapshot, a positive server wait is honored with a platform sleep cap; the older description that only waits of 60 seconds or less are honored does not match this source. Check the SDK version you deploy before relying on implementation details. For this application helper, a 120-second wait with only 30 seconds remaining stops the request immediately; it never becomes an early 30-second retry.

We checked the helper offline with mocked responses and a clock, including a wait that exceeds the budget, exhaustion without an extra sleep, successful recovery, and explicit no-retry. No model request or outage-recovery test was performed. Validate the policy in your application before enabling it for production traffic.

Reduce repeated overload by controlling incoming work

Retry controls prevent a single job from running forever. Admission controls prevent many jobs from retrying together. Start with the workers and queues you already operate:

1. Reduce active calls. Lower the worker concurrency or semaphore limit for the affected model or endpoint. As an initial experiment, halve the current limit while holding the request shape steady; this is a diagnostic choice, not a guaranteed fix. Record completed calls, 529 rate, and latency before increasing it again.
2. Keep the queue bounded. Store a job's expiry time when it enters the queue, check it before dispatch, and drop or return expired work. A retry window that begins only at dispatch does not account for time the user already spent waiting.
3. Defer optional work. Pause batch enrichment, previews, or other non-urgent generation. Show interactive users a clear retry-later outcome instead of silently launching another loop.
4. Pause admission during persistent failure. A circuit breaker can reject or defer new work after your chosen failure threshold. After a cooldown, admit a small number of checks; repeated failure keeps it open, while completed calls let you restore concurrency gradually.

Choose circuit-breaker thresholds from your traffic volume and tolerance for delayed work. One low-volume failure should not automatically produce the same response as sustained failures across many callers. Count final job outcomes as well as attempts so extra retries do not make request volume look like productive throughput.

These are application-design recommendations based on temporary overload and retry ownership. They do not guarantee additional provider capacity. Smaller requests may reduce the work you ask the service to do, but rewriting a prompt is not a demonstrated repair for a clean 529.

Keep streaming and fallback decisions separate from retry scheduling

Anthropic documents that a stream can fail after HTTP 200. Record both the initial response and the eventual completion or error; do not mark a job successful merely because the HTTP connection opened. Source: streaming error boundary.

The helper above covers a returned status error, not a failed partial stream. If your application has already shown output or executed a tool, retain that state and reconcile completed actions before restarting. A new generation is not a documented token-offset continuation. Blindly appending a replay can duplicate text; blindly executing repeated tool instructions can duplicate external changes. Stream completion and tool de-duplication belong in the application's workflow handling.

A different model or provider can be a fallback when it is already available to your application and the task accepts its output. Verify supported tools, output schema, context requirements, permissions, and user-visible differences before routing work there. A second API key alone does not establish an independent capacity pool. Keep fallback success distinct from recovery of the original model and endpoint.

Verify recovery and collect evidence if 529 persists

After a cooldown or concurrency change, admit a small request on the failing model and endpoint. Keep the input shape and gateway path comparable. A completed response shows that attempt succeeded; it does not establish sustained recovery. Watch subsequent eligible jobs and restore load gradually, checking completion rate, 529 frequency, queue age, and latency together.

If the retry budget ends and the same path continues failing, retain a compact record for the service that answered:

• Timestamp and timezone, HTTP status, error type and message, and request_id or the request-id response header when present.
• Model, endpoint or gateway host, SDK version, and whether the route is direct Anthropic or another provider.
• Attempt count, elapsed time, server wait headers, SDK retry settings, and the application's final outcome.
• Concurrent-call limit, queue age, relevant status-page observation, and the result of the recovery check.
• A minimal reproduction with credentials, private prompts, and customer data removed.

Anthropic's request ID documentation says the body and header identifiers normally match; successful Python response objects expose _request_id. Distinct attempts can have distinct request IDs. Correlate them with your own job ID rather than replacing every attempt ID with one invented identifier. A gateway may omit or rewrite upstream IDs, so preserve the identifiers actually returned.

Send direct Anthropic failures to Anthropic support and gateway-specific failures to the gateway operator. Keep both records if you can establish an upstream failure. Stop automatic retries once the job expires or its attempt limit is reached; a support investigation does not require continuing stale traffic.

Frequently asked questions

Is Claude API 529 a rate limit?

No. On the direct Claude API, 529 overloaded_error means temporary overload. 429 rate_limit_error can mean a rate limit or certain spend limits, including a tier spend-cap case that keeps failing until access resumes. Use the actual status and body to choose the response. Source: API errors.

Does “send failed: overloaded” always mean HTTP 529?

No. The text alone does not show the underlying HTTP response. Inspect the wrapper's error details or logs. If this is Claude Code, let an active retry finish and use the session recovery guide before repeating work that may have completed.

How many times does the Python SDK retry a 529?

The documented default is two retries for eligible failures, for up to three HTTP attempts including the initial one. Configure max_retries if another part of your service owns the policy. A response can stop retrying earlier. Source: Python SDK retries.

Will setting timeout to 20 seconds enforce a 20-second total deadline?

No. The SDK's request timeout and your application's total deadline are different controls. Retries, backoff, queue time, and transport behavior can extend elapsed time. Enforce a hard deadline through your application runtime and cancellation integration when your product requires one. Source: SDK timeouts.

What if Retry-After is longer than my request can wait?

Stop or defer the job rather than retrying before the server-directed wait. For example, a 120-second wait cannot fit a 30-second remaining retry window. Defer only if the job is still useful and your queue supports scheduling it later; otherwise return a temporary-unavailable outcome.

Why do I still get 529 when Claude Status is green?

A public status page does not prove that a particular model, endpoint, or gateway path can finish your request. Keep retries bounded, reduce concurrent traffic, and check completion on the failing path. If it still fails, retain the actual request IDs and retry timeline for support.