Immutable solution version
Rate-limit-aware retries for the Claude API
Complete solution
Shows how to fix rate-limit-aware retries for the Claude API. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.
TL;DR
Limits apply per organization. Track remaining against reset in your client and shed load before you hit zero: client-side throttling beats server 429s. Wait it out with exponential backoff and jitter on top. Detect the missing retry-after and surface "usage paused" to the user instead of looping.
When to use
You are seeing this: Retry like you read the headers. Use this skill when you run into "Rate-limit-aware retries for the Claude API".
When not to use
If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.
Versions
No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.
Retry like you read the headers.
- Know the limit model. Limits apply per organization. Start, Build, and Scale tiers each carry a monthly spend cap: the maximum the org can spend per calendar month. Higher tiers raise the caps; if you are planning scale, sort the tier before you need it.
- Read the headers on every response. Responses carry anthropic-ratelimit-requests-limit, remaining, and reset, plus input-tokens and output-tokens variants. Track remaining against reset in your client and shed load before you hit zero: client-side throttling beats server 429s.
- Honor retry-after on 429. A ratelimiterror may include a retry-after header telling you how long to wait. Wait it out with exponential backoff and jitter on top. The SDKs retry automatically on some errors: know exactly which errors yours retries so you do not double-retry.
- Distinguish paused usage from rate limits. When the org hits its monthly spend cap, usage pauses and requests return 429 with the same ratelimiterror type but no retry-after header. Retrying, including SDK automatic retries, fails until access resumes. Detect the missing retry-after and surface "usage paused" to the user instead of looping.
- Separate retryable from fatal. Retry 429s and 529 overloaded errors. Do not retry 400s (bad request, including rejected thinking parameters), 401s (bad key), or 404s: those need a code or config fix, and retrying them burns quota.
- Queue, do not hammer. For bulk workloads, put requests in a queue with a concurrency cap derived from the rate-limit headers instead of firing all at once and relying on retries. Consider the Message Batches API for non-urgent bulk work: it is built for throughput and costs half.
Evidence
Claims verified against Anthropic's official docs (platform.claude.com) on 2026-09-26. Evidence URLs in public_references.
By @issueatlas · Version 2 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_EHBA5Z4PVhUmARDUNXV7Kg" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Rate-limit-aware retries for the Claude API <span>— Vectle</span></a>