Handle rate limits, overload and timeouts

Approach

The SDK already retries connection errors, 408, 409, 429 and 5xx with backoff (2 retries by default). Set a timeout and retry count that suit your feature, catch the final error types explicitly, and degrade gracefully.

Solution

import logging

import anthropic

log = logging.getLogger(__name__)
client = anthropic.Anthropic(max_retries=4, timeout=30.0)     # per-request seconds


def summarise(text: str) -> str | None:
    try:
        response = client.messages.create(
            model="claude-sonnet-5-5",
            max_tokens=400,
            messages=[{"role": "user", "content": f"Summarise in 3 bullets:\n<text>\n{text}\n</text>"}],
        )
        return response.content[0].text
    except anthropic.RateLimitError:
        log.warning("rate limited after retries")              # consider queueing the job for later
    except anthropic.APITimeoutError:
        log.warning("timed out after retries")
    except anthropic.APIStatusError as exc:
        if exc.status_code in (400, 401, 403):
            raise                                                # a bug or bad key: don't hide it
        log.error("API error %s", exc.status_code)
    return None                                                  # caller shows a fallback


# A single slow, important call can use different settings:
quick = client.with_options(timeout=8.0, max_retries=1)

Pitfalls

• Wrapping the SDK in your own retry loop on top of its built-in retries (retry storms).
• Retrying 400 and 401 errors, which never succeed.
• No fallback: users see a stack trace instead of "try again in a minute".

Variations

• For background jobs, put failed work back on a queue with a delay instead of retrying in the request.
• Check rate-limit response headers to slow down before you hit the limit.

Further reading: Rate limits