Many parallel agents hit HTTP 429 'rate_limit_error' (or 529 'overloaded_error') on the Claude API: how do I set concurrency caps, queues and token budgets, and tell a rate limit from a spend cap?

Cause: Claude API rate limits are enforced per organization (and optionally per workspace) as requests per minute, input tokens per minute and output tokens per minute for each model class. A fleet of agents shares one pool, and capacity is a token bucket that refills continuously, so short bursts can trip a limit even when the per-minute average is fine. A sharp jump in traffic can also trigger acceleration limits. A 529 means the API is overloaded across all users and is separate from your limits. Fix (best first): 1. Honor retry-after. When a 429 carries a retry-after header, wait at least that many seconds; earlier retries fail. The official SDKs retry transient failures with exponential backoff, twice by default, and respect the header; max_retries is configurable. 2. Cap concurrency centrally. Put a shared semaphore or work queue in front of all agents so total in-flight requests and tokens stay under your limits, rather than letting each agent retry independently. Add jitter to backoff so agents do not retry in lockstep. 3. Ramp up gradually. Start workers in stages and keep usage consistent to avoid acceleration limits. 4. Use prompt caching. For most models, cache_read_input_tokens do not count toward input-tokens-per-minute, so caching shared system prompts, tool definitions and large context raises effective throughput. Check the rate limit table's footnotes for exceptions. 5. Budget tokens. Track the anthropic-ratelimit-*-remaining and -reset response headers and slow down before hitting zero. Keep per-agent context lean (see tool-result truncation) and send non-urgent work through the Message Batches API, which has separate limits. 6. Isolate workloads. Use workspaces to give batch or experimental agents their own lower limits so they cannot starve interactive ones; organization limits still apply overall. 7. Tell apart a spend cap: a 429 with error code enforced_spend_limit_reached has no retry-after header and will keep failing until access resumes or the tier changes, so retrying is pointless. A spend limit you set yourself returns a 400 invalid_request_error instead. 8. For 529 and 5xx errors, retry with exponential backoff; log the request-id header when contacting support. Verify: Run the fleet at target concurrency and confirm 429s are rare and every one is followed by a successful retry, the remaining-header values do not sit at zero, and no job fails on a spend-cap error. Sources: https://platform.claude.com/docs/en/api/rate-limits https://platform.claude.com/docs/en/api/errors