Claude API 529 Overloaded — How to Diagnose and Fix It

Before writing retry logic, determine whether Anthropic is having a platform-wide outage or whether your 529s are isolated. The fastest way is the Prismix status dashboard, which polls Anthropic's API and aggregates incident reports in real time.

The official Anthropic Python and TypeScript SDKs automatically retry 429 and 529 errors with exponential backoff. The default is 2 retries — increase it for production workloads:

# Python — increase SDK retries to 5 (covers most transient 529 spikes)
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    max_retries=5,   # default is 2; max recommended is 8
    timeout=60.0,    # seconds per attempt
)

// TypeScript — same pattern
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  maxRetries: 5,
  timeout: 60_000,  // ms
});

With max_retries=5, the SDK will wait approximately 1 s, 2 s, 4 s, 8 s, and 16 s between attempts (with jitter) before surfacing the error to your code. This covers the vast majority of short 529 spikes with zero extra code.

For batch processing or server-side jobs, write an explicit retry wrapper that handles 529 separately from 429, caps wait time, and logs each attempt:

import time
import random
from anthropic import Anthropic, APIStatusError

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"], max_retries=0)

def create_with_backoff(max_attempts: int = 6, **kwargs):
    """Retry on 429 and 529 with exponential backoff + jitter."""
    for attempt in range(max_attempts):
        try:
            return client.messages.create(**kwargs)
        except APIStatusError as e:
            if e.status_code not in (429, 529):
                raise  # don't retry auth or validation errors
            if attempt == max_attempts - 1:
                raise
            wait = min(60.0, (2 ** attempt) + random.uniform(0, 1))
            label = "overloaded (529)" if e.status_code == 529 else "rate-limited (429)"
            print(f"Claude API {label}. Retry {attempt + 1}/{max_attempts - 1} in {wait:.1f}s")
            time.sleep(wait)

# Usage
response = create_with_backoff(
    max_attempts=6,
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)

// TypeScript async version
import Anthropic, { APIError } from '@anthropic-ai/sdk';

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY, maxRetries: 0 });

async function createWithBackoff(params: Anthropic.MessageCreateParamsNonStreaming, maxAttempts = 6) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await client.messages.create(params);
    } catch (e) {
      if (!(e instanceof APIError) || ![429, 529].includes(e.status)) throw e;
      if (attempt === maxAttempts - 1) throw e;
      const wait = Math.min(60_000, (2 ** attempt) * 1000 + Math.random() * 1000);
      console.warn(`Claude API ${e.status} — retry ${attempt + 1} in ${(wait / 1000).toFixed(1)}s`);
      await new Promise(r => setTimeout(r, wait));
    }
  }
}

During a prolonged 529 incident, retrying every request wastes resources and queues up a backlog. A circuit breaker stops sending requests after a failure threshold, waits a fixed recovery window, then probes before resuming:

import time

class CircuitBreaker:
    def __init__(self, failure_threshold=3, recovery_timeout=60):
        self.failures = 0
        self.threshold = failure_threshold
        self.timeout = recovery_timeout
        self.opened_at = None
        self.state = "closed"  # closed | open | half-open

    def record_failure(self):
        self.failures += 1
        if self.failures >= self.threshold:
            self.state = "open"
            self.opened_at = time.monotonic()
            print(f"Circuit OPEN — pausing Claude API calls for {self.timeout}s")

    def record_success(self):
        self.failures = 0
        self.state = "closed"

    def allow_request(self) -> bool:
        if self.state == "closed":
            return True
        elapsed = time.monotonic() - self.opened_at
        if elapsed >= self.timeout:
            self.state = "half-open"
            return True  # probe request
        return False

breaker = CircuitBreaker()

def safe_create(**kwargs):
    if not breaker.allow_request():
        raise RuntimeError("Claude API circuit open — skipping request")
    try:
        result = client.messages.create(**kwargs)
        breaker.record_success()
        return result
    except APIStatusError as e:
        if e.status_code == 529:
            breaker.record_failure()
        raise

Overload is often model-specific. If claude-3-5-sonnet or claude-opus-4-8 returns 529s persistently, claude-3-5-haiku-20241022 (lighter infrastructure) may still be available:

MODEL_FALLBACK_CHAIN = [
    "claude-3-5-sonnet-20241022",
    "claude-3-5-haiku-20241022",   # lighter — often available during partial outages
]

def create_with_fallback(**kwargs):
    for model in MODEL_FALLBACK_CHAIN:
        try:
            return client.messages.create(model=model, **kwargs)
        except APIStatusError as e:
            if e.status_code == 529 and model != MODEL_FALLBACK_CHAIN[-1]:
                print(f"{model} overloaded — trying {MODEL_FALLBACK_CHAIN[1]}")
                continue
            raise

• Off-peak hours: UTC 02:00–08:00 typically has the lowest Claude API load. Schedule heavy batch jobs in this window.
• Prompt caching: reducing token load per request by caching your system prompt with cache_control: {"type": "ephemeral"} can decrease the probability of hitting 529 on high-throughput workloads.