Anthropic returns 429 rate_limit_error when an organization hits a rate limit, reaches its usage tier's monthly spend cap, or reaches a spend limit on the Claude Code workspace. The Messages API uses RPM + input TPM + output TPM. A rate-limit 429 carries a retry-after header; a spend-cap 429 (error_code enforced_spend_limit_reached) has no retry-after and keeps failing until access resumes.
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.
- The usage tier's monthly spend cap or a Claude Code workspace spend limit was reached; the body names error_code enforced_spend_limit_reached and the date access resumes.
How do you diagnose it?
- Read the error body: check for details.error_code before assuming a throughput problem, and note whether a retry-after header is present.
- 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?
- For throughput limits, wait at least retry-after before retrying, smooth traffic and ramp volume gradually.
- For a spend cap, raise the tier or spend limit or wait for the stated reset date; retrying will not clear it.
- 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.