Rate Limit Headers: Reading X-RateLimit-* to Adapt in Real Time

Many APIs use X-RateLimit-* header names, and you'll often hear the concept called that generically. On the Claude API the headers carry an anthropic- prefix instead, but they do the same job: on every response, they report your current limits, remaining capacity, and reset times, so a well-built client can adapt in real time rather than reacting to failures.

The header set

The pattern is anthropic-ratelimit-<resource>-<field>, with four resources and three fields:

Each resource exposes -limit (the ceiling), -remaining (what's left; token values are rounded to the nearest thousand), and -reset (an RFC 3339 timestamp for when the bucket replenishes). On a 429 you additionally get retry-after, the number of seconds to wait. Organizations on Priority Tier see parallel anthropic-priority-* variants.

One subtlety: the tokens-* family reflects whichever limit binds right now — if a workspace-level cap is tighter than the organization limit, that is what you'll see. Limits are enforced per model with a token-bucket algorithm, meaning capacity replenishes continuously rather than resetting on a fixed interval.

What actually counts against each bucket

Two accounting rules make headroom bigger than it looks. First, ITPM is cache-aware on most models: input_tokens and cache_creation_input_tokens count, but cache_read_input_tokens do not — so with an 80% cache hit rate, a 2M ITPM limit effectively processes 10M total input tokens per minute. Aggressive prompt caching is a rate-limit strategy, not just a cost strategy. Second, OTPM counts only tokens actually generated, in real time; your max_tokens setting doesn't factor in, so a generous max_tokens has no rate-limit downside.

Building the adaptive loop

The official SDKs already retry 429s with exponential backoff and honor retry-after. The headers let you go one better: slow down before the 429.

from anthropic import AnthropicAWS
import time, datetime

client = AnthropicAWS()
resp = client.messages.with_raw_response.create(
    model="claude-sonnet-5", max_tokens=1024, messages=history)
h = resp.headers
remaining = int(h["anthropic-ratelimit-input-tokens-remaining"])
limit = int(h["anthropic-ratelimit-input-tokens-limit"])
if remaining < limit * 0.1:                       # under 10% headroom
    reset = datetime.datetime.fromisoformat(
        h["anthropic-ratelimit-input-tokens-reset"])
    pause = (reset - datetime.datetime.now(datetime.UTC)).total_seconds()
    time.sleep(max(pause, 0))
msg = resp.parse()

In a multi-worker system, feed -remaining into a shared budget (a semaphore or token bucket of your own) instead of sleeping per worker. And ramp traffic gradually when launching or scaling: sharp spikes can trigger 429s from acceleration limits even when you are under your steady-state numbers.

The 3P picture

These headers belong to the Claude API surface. Claude Platform on AWS uses the same rate-limit system, with one caveat: organizations there stay on the Start tier (no automatic tier movement), and spend limits and per-workspace rate-limit configuration are unavailable. Amazon Bedrock, Google Vertex AI, and Microsoft Foundry meter Claude through their own cloud-native quota systems with their own signaling, so this header set does not apply there — on Bedrock, for example, throttling arrives as the service's own exception type (see Bedrock throttling handling and Bedrock quota types).

Where to go next

For what happens when you do hit the wall, read the error taxonomy. To stretch your ITPM budget, see prompt cache mechanics, and for volume that doesn't need to be real-time, batch processing.

Sources

• Rate limits — Claude Docs
• API errors — Claude Docs