The Claude API enforces rate limits per organization, per model, across three dimensions: requests per minute (RPM), input tokens per minute (ITPM), and output tokens per minute (OTPM). What matters for resilience engineering is how those limits are enforced. Anthropic documents that they use a token-bucket algorithm with continuous replenishment — not a fixed-interval reset. In a fixed-window scheme, capacity snaps back to full at the top of each minute. In a token bucket, you hold a reservoir of capacity that drains as you use it and refills smoothly, moment by moment, at your per-minute rate. There is no magic second when everyone's quota refreshes.
What continuous replenishment changes in practice
Bursts spend savings, not the future. A token bucket lets you burst up to whatever capacity has accumulated in the bucket, then constrains you to the refill rate. If you've been quiet for a while, you can absorb a spike; if you've been running flat out, there is no headroom, and the next request over the line gets a 429 rate_limit_error. This is why the same burst succeeds at 9:00 and fails at 9:05 — the bucket's fill level, not the wall clock, decides.
Waiting "until the next minute" is the wrong backoff. Because capacity trickles back continuously, the correct wait after a 429 is whatever the API tells you. Every 429 names the limit you exceeded and carries a retry-after header with the number of seconds to wait. The official SDKs honor it automatically, retrying with exponential backoff (twice by default). If you write your own retry loop, read that header rather than sleeping to a minute boundary — you'll usually wait less, and you'll never retry too early.
Smooth beats spiky, even under quota. Anthropic additionally documents acceleration limits: sharp spikes in usage can trigger 429s even when you are technically inside your steady-state numbers. The guidance is to ramp traffic gradually — a big-bang launch that jumps from near-zero to full quota in seconds is exactly the pattern the token bucket punishes. If you're planning a migration or load test, see ramping up under acceleration limits.
Reading the headers correctly
Every Claude API response reports live rate-limit state through headers of the form anthropic-ratelimit-{requests,tokens,input-tokens,output-tokens}-{limit,remaining,reset} (some documentation and third-party tooling refers to these generically as "X-RateLimit" headers — the actual names carry the anthropic- prefix). Three details are easy to misread:
| Header behavior | What it actually means |
|---|---|
...-reset is an RFC 3339 timestamp | The time when the bucket would be fully replenished — not a window boundary after which "everything resets." Capacity is already flowing back before that instant. |
...-remaining for tokens is rounded to the nearest thousand | Treat it as a gauge, not an exact accounting; don't build logic that depends on small differences. |
anthropic-ratelimit-tokens-* shows the most restrictive limit in effect | If a workspace-level limit binds tighter than the organization limit, that's what you're seeing. |
One planning-relevant asymmetry: OTPM counts only tokens actually generated, in real time — max_tokens does not factor in, so setting a generous max_tokens has no rate-limit downside on the Claude API. And limits are shared across inference_geo values, so routing some traffic "us" and some "global" draws from the same per-model pool.
retry-after exactly, and alarm on the -remaining headers trending toward zero rather than on 429s after the fact.Does this transfer to the 3P platforms?
Only partially. The token-bucket mechanics and anthropic-ratelimit-* headers are documented for the Claude API, and Claude Platform on AWS uses the same rate-limit system (with organizations remaining on the Start tier). Elsewhere, throttling is the cloud provider's job: Microsoft Foundry explicitly does not return Anthropic's rate-limit headers — Anthropic directs you to Azure's monitoring instead — and Bedrock and Vertex AI enforce their own quota models with their own signals. Never port header-parsing code to a 3P platform without checking that platform's documentation first.
Where to go next
The full header vocabulary lives in rate-limit headers. For why a high cache hit rate multiplies what a given ITPM quota can do, read ITPM and cache reads; for splitting limits across teams, see workspace rate-limit configuration.