What is Rate limit (HTTP 429)?
A cap on how many requests or tokens you can send in a given window (per minute, per day). When exceeded, the provider returns HTTP 429 'Too Many Requests' with an x-ratelimit-reset header telling you when the window resets. Common causes: heartbeat firing too often, retry loops after errors, free-tier daily cap, or provider-wide throttling. Mitigations: provider fallback in config, exponential backoff on retries, cheaper models for routine tasks, or upgrading your plan tier.
What is limited
In the Claude API, rate limits cap how much an organisation can use over a period. For the Messages API they are measured per model class in requests per minute, input tokens per minute and output tokens per minute. Limits depend on your usage tier, are set at organisation level, and can be tightened further per workspace. They are maximums, not guaranteed minimums.
What happens when you hit one
You get a 429 error that says which limit was exceeded, and often a retry-after header giving the seconds to wait; earlier retries fail. The API uses a token bucket, so capacity refills continuously rather than resetting at fixed times, and short bursts can trip a limit even when your per-minute average is fine. Most Claude models do not count cached input tokens toward the input limit, so prompt caching raises your effective throughput.
Rate limits are not spend limits
Spend limits are a separate cap on monthly cost. Anthropic documents that reaching the tier cap returns a 429 of the same rate_limit_error type but with no retry-after header, so retrying, including an SDK's automatic retries, fails until the next month starts or the limit is raised. A spend limit you set yourself returns a 400 instead.
Example
An agent loop sends requests faster than the per-minute budget and starts receiving 429s. It should wait the retry-after number of seconds, slow its pace, and cache the large repeated prefix so each request counts for less.
Sources
See also
← Back to the full AI agent glossary.