Make Claude API calls resilient by reading the rate-limit response headers and handling 429 versus 529 with the correct backoff

Documented steps

1. On every /v1/messages response, read anthropic-ratelimit-requests-limit / -remaining / -reset and the parallel input-tokens and output-tokens triplets (anthropic-ratelimit-input-tokens-limit/-remaining/-reset, anthropic-ratelimit-output-tokens-limit/-remaining/-reset). Reset values are RFC 3339 timestamps.
2. Also read anthropic-ratelimit-tokens-limit/-remaining/-reset, which reflect whichever of input or output is currently most restrictive.
3. If you are on Priority Tier, additionally track anthropic-priority-input-tokens-* and anthropic-priority-output-tokens-*, which are a separate budget from the standard pool.
4. On HTTP 429 (error.type rate_limit_error), read the retry-after header in seconds and sleep exactly that long. Do not guess.
5. On HTTP 529 (overloaded_error) treat it as platform-wide capacity, not your quota: retry-after may be absent, so use exponential backoff with jitter.
6. Ramp traffic gradually. Limits use a continuously replenishing token bucket, so a sharp burst can trigger 429s even while you are under your nominal tier cap.
7. Budget cached prompts correctly: for most models only uncached input_tokens plus cache_creation_input_tokens count toward input tokens per minute; cache_read_input_tokens is excluded (Claude Haiku 3.5 is the exception and does count reads).
8. Choose service_tier per request among standard, priority, and batch. The Message Batches API has its own limits: 1,000 requests/minute, 100,000 requests per batch, 200,000 requests queued.
9. Log the request_id from the response header and from the error body {"type":"error","error":{...},"request_id":...} for support escalation.
10. Prefer the official SDK max_retries option over hand-rolled retry logic; it already covers connection errors, 429, and 5xx/529.
11. Official docs: https://platform.claude.com/docs/en/api/rate-limits and https://platform.claude.com/docs/en/api/errors