Build Anthropic API resilience in this order: read your organization’s actual limits, smooth traffic across requests and tokens, classify each error before retrying, and set a finite retry deadline. A 429 is not always a temporary rate limit, and retrying the same request does not automatically switch models. The right fallback is an application decision based on whether another active model can safely do the same job.
How Anthropic API rate limits work
The Messages API measures usage in three separate dimensions: requests per minute (RPM), input tokens per minute (ITPM), and output tokens per minute (OTPM). Limits depend on your organization’s tier and model class; they are maximums, not guaranteed minimum capacity. Organization limits apply across the organization, with workspace-level limits able to impose lower caps. Check the current Anthropic rate limits documentation and your account rather than hard-coding a tier table.
As an Amazon Associate I earn from qualifying purchases.
Anthropic’s documentation says, “The API uses the token bucket algorithm to do rate limiting.” Capacity replenishes over time, so staying below a per-minute average does not ensure every burst will pass: enforcement can occur over shorter intervals. Limits are applied separately for each model, while requests with different inference_geo values share a pool. Most Claude models count uncached input tokens toward ITPM; input usage is estimated when a request starts and adjusted as actual usage becomes known. OTPM is evaluated as generated tokens are produced, and the max_tokens setting itself does not count toward OTPM.
Find the limits that apply to your account
Use the Console’s current limits view or Anthropic’s Rate Limits API to inspect configured capacity for the organization and relevant model class. Response headers also report limit, remaining capacity, and reset time. Treat those live values as more useful for traffic control than a static example in documentation: the documented Claude Fable 5.x row of 1,000 RPM, 500,000 ITPM, and 100,000 OTPM is model-specific, not a general entitlement.
Smooth traffic instead of releasing bursts
Anthropic notes that a sharp increase in usage can trigger acceleration-related 429 errors, even if the organization has not sustained the new rate long enough to exceed an ordinary per-minute budget. Ramp traffic gradually and avoid synchronized bursts, such as releasing a large queue all at once. As an implementation recommendation, use a queue or concurrency limiter that considers the tightest relevant dimension—requests, input tokens, and output tokens—rather than limiting requests alone. A process-local limiter is simple for one service instance; a shared limiter or gateway is needed when several instances could collectively exceed the same organization budget.
What to do when Anthropic returns 429
Read the error type and headers before deciding to retry. Anthropic documents 429 responses for more than one condition, and treating all of them as temporary rate limits can create a loop that never succeeds. See the Claude API error documentation for the current response behavior.
Rank #2
| Response condition | How to respond |
|---|---|
429 rate_limit_error with retry-after |
Wait at least the indicated interval before retrying. Anthropic says an earlier retry is expected to fail. Keep the retry within your application’s time budget. |
429 rate_limit_error without retry-after |
Investigate a spend cap or another non-temporary restriction. A tier monthly spend-cap 429 continues failing until access resumes; do not retry indefinitely. Claude Code workspace spend limits are also documented as a possible cause. |
| 429 during a sharp traffic increase | Reduce or smooth incoming traffic and ramp up gradually; the error may reflect acceleration limits rather than only the minute-level average. |
If a spend cap is responsible, the useful next step is account or budget action, not a longer backoff. For a true rate-limit response, honor retry-after even when your own exponential-backoff calculation would choose a shorter wait.
How many times does the Anthropic SDK retry?
Anthropic’s official SDKs retry transient failures—including connection errors, rate limits, and 5xx errors—with exponential backoff twice by default. They honor retry-after when it is present. The SDK exposes max_retries to change or disable automatic retries; check the documentation for the language-specific SDK you use before adding application-level retry logic.
Two SDK retries are not a promise that the full operation will finish within your service’s latency budget. Set a finite total deadline and an attempt budget for the whole request path, including SDK retries. Avoid wrapping the SDK in a large, unbounded retry loop: nested policies can multiply attempts and extend latency unexpectedly. Record the error category and request ID, then return a clear failure when the deadline expires. These deadline and logging practices are application design recommendations, not Anthropic API requirements.
Which errors should you retry?
Use status, error type, and response headers together. Anthropic’s documented distinctions are useful because they imply different recovery actions.
| Error | Meaning | Recommended handling |
|---|---|---|
500 api_error |
Unexpected internal API error. | Retry with bounded exponential backoff. If it persists, contact Anthropic support and include the request ID. |
504 timeout_error |
Request processing timed out. | For long-running Messages requests, consider streaming. A retry may be appropriate only within the operation’s deadline and workload policy. |
529 overloaded_error |
Temporary API overload. | Use bounded retry/backoff. If the operation still cannot proceed, apply your queue, controlled-error, or fallback policy. |
429 rate_limit_error |
Rate limit, spend cap, or another documented usage limit. | Check retry-after and determine whether the condition is temporary before retrying. |
Streaming has a separate failure path: an SSE error can arrive after the server has already returned HTTP 200. Handle stream events as well as the initial HTTP response; a request-level check for non-200 statuses will not catch every mid-stream failure.
Should you retry a 529 or fall back to another model?
A 529 means temporary overload, so a bounded retry is reasonable; it does not by itself select another model. Anthropic’s direct Claude API documentation does not prescribe one universal fallback algorithm. Decide in your application whether to keep waiting, defer work in a queue, return a controlled error, or route to another model or provider.
- Classify the failure. For a temporary 429, honor
retry-after; for a spend-cap 429, stop retrying and surface the account or budget action required. - Use a bounded retry policy. Retry only transient failures, with backoff and an operation deadline. Account for the official SDK’s two default retries before adding another layer.
- Choose the next action when the budget expires. Queue or defer work, return a controlled failure, or initiate a fallback only if the alternate route is authorized and appropriate for the task.
- Validate the fallback. Check task quality, output format and schema compatibility, tool support, latency, cost, model lifecycle status, and geographic or data-routing requirements.
Model availability changes. Anthropic’s model deprecation guidance advises moving from deprecated models to suitable active replacements before retirement; requests for retired models fail. Keep fallback configuration current rather than assuming a previously available model will remain usable.
Choosing traffic controls and routing
For a single service instance, an in-process queue or limiter can smooth traffic with relatively little operational overhead. It cannot coordinate a shared organization budget across independently running instances unless those instances share state. A shared gateway can coordinate routing and provide centralized visibility, but it adds operational and security ownership.
| Approach | Useful when | Trade-off |
|---|---|---|
| In-process limiter or queue | A small service has one instance or can safely manage its own traffic. | Simple to operate, but separate instances do not automatically share capacity or observability. |
| Shared gateway | Several services or instances need coordinated limits, load balancing, fallback routing, usage tracking, or cost controls. | More routing flexibility and centralized controls, with added operational burden and responsibility for gateway security and behavior. |
Anthropic documents LiteLLM as a third-party proxy option for gateway functions and explicitly says it does not endorse, maintain, or audit LiteLLM’s security or functionality. It is not an Anthropic product, so assess and operate it as an external dependency. Anthropic’s legacy Claude on Amazon Bedrock documentation specifically steers readers away from that integration’s server-side fallbacks parameter toward a client-side fallback pattern; that guidance is integration-specific, not a universal direct API setting. The same page distinguishes global endpoints, which dynamically route for availability, from regional endpoints intended for data-routing requirements. Choose routing that satisfies your own residency constraints rather than assuming availability routing meets them.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
