Anthropic documents 429 rate_limit_error when an account hits a rate limit. The Messages API uses RPM + input TPM + output TPM, and the retry-after header tells you the minimum wait.
Why does this error happen?
- Requests per minute were exhausted.
- Uncached input-token or output-token throughput reached its limiter.
- Traffic accelerated sharply enough to trigger an acceleration limit.
How do you diagnose it?
- Read the error body and retry-after header.
- Inspect anthropic-ratelimit-* headers for the most restrictive active limiter.
- Compare traffic by model because model groups can have separate pools.
How do you fix it?
- Wait at least retry-after before retrying.
- Smooth traffic and ramp volume gradually.
- Use prompt caching where applicable and request higher limits only after measuring the actual bottleneck.
How do you prevent it from recurring?
Turn the confirmed cause of 429 — rate_limit_error into an observable boundary for Anthropic API. Track the relevant request count, token volume, payload size, execution time, connection pressure, billing state, or upstream health before it reaches the documented failure condition. Preserve the platform request ID and timestamp so future incidents can be correlated without logging sensitive payloads.
Test the fix under representative concurrency and failure injection, not only with one successful request. Alert on remaining headroom and repeated retries, and keep the linked limit page and official error source with the runbook so responders can distinguish a configuration problem from temporary service pressure or account state.