Rate limits show up at deployment, but they start as a design problem. A tool that works for one tester can fail once a whole team uses it at 9am, because nobody worked out how many tokens each request sends. The arithmetic isn’t hard. It just has to happen before the architecture is fixed.
We build custom Claude tools through our AI integration service, so weigh that. Every fact below about the Claude API was last checked against Anthropic’s own documentation in October 2026.
Short answer: The Claude API limits each organization per model on requests per minute (RPM), input tokens per minute (ITPM) and output tokens per minute (OTPM). Go over any one and you get a 429 error with a retry-after header. Capacity refills continuously, so short bursts can trip a limit even when your average looks fine. The biggest lever is prompt caching: on most current models, tokens read from cache don’t count toward ITPM. Then count what each request really sends, batch work that can wait, cap background jobs with workspace limits, and retry with backoff.
What Anthropic Documents About Rate Limits
As of October 2026, from Anthropic’s Claude API documentation:
| Topic | What the docs say |
|---|---|
| Limit types | RPM, ITPM and OTPM, set per model |
| How limits refill | Token bucket: continuous refill, not a fixed reset |
| Usage tiers | Start, Build, Scale and Custom; new organizations may begin in a lower Evaluation tier |
| Start tier, Sonnet 5.5 | 1,000 RPM, 2M ITPM, 400K OTPM |
| Build tier, Sonnet 5.5 | 5,000 RPM, 5M ITPM, 1M OTPM |
| Scale tier, Sonnet 5.5 | 10,000 RPM, 10M ITPM, 2M OTPM |
| Monthly spend cap | Start $500, Build $1,000, Scale $200,000 |
| Cached input | Cache reads don’t count toward ITPM on most models |
| 429 error | rate_limit_error, with a retry-after header |
| 529 error | overloaded_error: the API is busy across all users |
| Batch API | 50% off; separate rate limits; most batches finish within an hour |
Sources: Anthropic rate limits, API errors, pricing, batch processing.
Opus 5.5, Sonnet 5.5 and Haiku 5.5 share these numbers at each tier. Claude Fable 5.x has lower limits, such as 500,000 ITPM at the Start tier (source). Your own limits are on the Rate limits page in the Claude Console.
How Claude API Rate Limits Actually Work
Limits are set per organization, which Anthropic places on a tier automatically based on usage history and account standing. They are maximums, not guaranteed minimums (source).
The Three Limits That Govern Every Request
RPM counts requests, ITPM input tokens and OTPM output tokens. Exceed any of them and the 429 says which limit you hit (source). Many first builds watch only requests, then fail on input tokens.
ITPM is estimated when a request starts and adjusted to the real count. OTPM counts only tokens actually generated, so a high max_tokens setting costs no rate limit headroom (source).
Each tier also has a monthly spend cap. Reaching it returns a 429 too, but with no retry-after header and an error code of enforced_spend_limit_reached, and retrying won’t help until access resumes (source). Your code should tell the two apart.
Token Bucket vs. Fixed Interval, Why the Distinction Matters for Burst Traffic
With the token bucket algorithm, capacity refills continuously up to your limit instead of resetting each minute. Limits can also be enforced over shorter intervals: Anthropic’s example is 60 RPM enforced as one request per second (source).
So a team asking questions at the start of a meeting can trip a limit while the hourly average sits well under it. Design for your peak minute. A sharp jump in overall usage can also hit acceleration limits, so ramp traffic up gradually (source).
Where Custom Tools Burn Tokens Faster Than Expected
Most surprises come from tokens sent before the user types a word.
Tool Definitions, System Prompts, and History All Count
Every tool schema you define is billed as input: names, descriptions and schemas in the tools parameter, plus tool use and tool result blocks. When any tool is present, the API adds its own tool use system prompt, 286 tokens on Claude Sonnet 5.5 with automatic tool choice (source). Add your system prompt and the conversation so far, and input grows every turn.
Claude 4.7 and later models also use a newer tokenizer that produces about 30% more tokens for the same text (source). Anthropic’s token counting endpoint accepts system prompts and tools, so measure a real request before you plan around it (source).
The Real Token Cost of a “Simple” Tool Interaction
Our own worked example, with assumed token counts. A sales assistant that looks up CRM data and drafts emails might send:
- System prompt: 2,500 tokens
- Tool definitions: 3,000 tokens
- Five earlier turns: 15,000 tokens
- The new question: 200 tokens
That’s 20,700 input tokens per request. The Start tier’s 2,000,000 Sonnet 5.5 ITPM fits about 96 of those a minute without caching (source). At $2 per million input tokens, each costs about 4 cents in input (source).
Model Selection Is a Rate Limit Decision, Not Just a Cost Decision
Rate limits apply separately to each model, so you can use different models up to their own limits at the same time (source). Routing part of your traffic to a second model gives it a second bucket. Some older models share one bucket, such as Opus 4.5 to 4.8.
Prices per million tokens, input then output: Fable 5.1 $10 / $50, Opus 5.5 $4 / $20, Sonnet 5.5 $2 / $10, Haiku 5.5 $0.10 / $0.50 for prompts up to 100,000 tokens (source).
When Haiku Is the Right Answer
Anthropic positions Haiku 5.5 for high-volume, latency-sensitive tasks such as classification, extraction and routing (source). On those prices, Opus 5.5 costs 40 times as much as Haiku 5.5 per token on a short prompt.
Our view: if your tool sorts, tags, extracts fields or answers from a fixed knowledge base, test Haiku first and keep it if the outputs hold up. For general work, Anthropic suggests starting with Opus 5.5 (source).
When to Reserve Opus, and How to Route Requests by Complexity
Use the larger models where reasoning quality changes the result: ambiguous inputs, multi-step analysis, high-stakes drafts. Route the rest with simple rules, such as request type or length. Each routine request you move frees headroom in the larger model’s bucket.
Designing for Rate Limits in Multi-User Client Tools
A personal tool can ignore most of this. A tool for a whole team can’t.
Multi-Tenant Token Math: How Many Concurrent Users Can Your Tier Handle?
Continuing our example: an active user sends two requests a minute at 20,700 input tokens, or 41,400 tokens a minute. The Start tier’s 2,000,000 Sonnet 5.5 ITPM covers about 48 users active in the same minute. With 800-token answers, OTPM allows about 250 such users and RPM about 500, so input tokens run out first.
Bursts trip limits sooner, and a new organization in the Evaluation tier starts lower (source). Check your real limits before you promise a rollout date.
Workspace Segmentation, Separating Batch from Interactive Traffic
A common failure: a nightly report job and a live assistant share one key, and the job leaves staff with 429 errors. Workspaces split usage inside one organization, each with its own API keys (source).
You can set spend and rate limits per workspace, below the organization’s. You can’t limit the default workspace, and organization-wide limits always apply (source). Give the background job its own capped workspace.
Better still, send work that can wait to the Message Batches API. It has its own rate limits, charges 50% of standard prices, and most batches finish within an hour (source).
Retry Logic, Exponential Backoff, and Respecting Retry-After Headers
The retry-after header gives the seconds to wait; earlier retries fail. anthropic-ratelimit-* headers show your limit, what remains and when it refills (source). Anthropic’s official SDK retries rate limits and 5xx errors twice by default with exponential backoff, honoring retry-after (source).
Our pattern on top:
- On a 429, wait at least the
retry-aftervalue, plus a little random jitter. - On repeated failures, back off further and cap the attempts.
- If the spend cap was reached, stop retrying and alert someone.
- Don’t show users a raw error. Queue the request and show it’s in progress.
Prompt Caching and Its Effect on Effective Throughput
Prompt caching reuses a prompt prefix from a recent request: tools, then system, then messages, in that order. A cache entry lives five minutes by default and refreshes each time it’s used (source).
What Cached Tokens Don’t Count Against
On most current models, cache reads don’t count toward ITPM; uncached input and cache writes do. Anthropic’s example: with 2,000,000 ITPM and an 80% cache hit rate, you could process 10,000,000 input tokens a minute. Claude Haiku 3.5 is the exception (source).
Cache reads still cost something. A hit on Sonnet 5.5 costs $0.10 per million tokens, 5% of the input price; a five-minute cache write costs 1.25 times the base input price (source).
When Caching Meaningfully Changes What Tier You Need
In our example, if the 5,500 tokens of system prompt and tools come from cache, each request counts 15,200 tokens toward ITPM, and the Start tier covers about 65 active users instead of 48. Caching history, or a long fixed catalogue or policy manual, gains more.
So turn on caching, watch your cache hit rate in the Console (source), and only then decide whether you need a higher tier. We work out these constraints at the scoping stage, before the build starts.
Related Posts
- Context window management in custom Claude tools: keeping each request’s tokens in check
- Custom AI tool resilience: error handling and fallbacks around the API
- Batch processing with AI: large-volume jobs without breaking live tools
- Custom AI tool economics: cost per use against a subscription
Frequently Asked Questions
What happens when a Claude API call hits a rate limit, does it fail silently or return an error?
It returns an error: HTTP 429, type rate_limit_error, naming the limit you exceeded, with a retry-after header. Wait, retry with backoff and queue the request rather than showing the user a raw error. A 429 from the monthly spend cap has no retry-after header and won’t clear by retrying.
What is the token limit per request for Claude, and how does tool use affect it?
Current models have a 1M-token context window and up to 128K output tokens (source). That’s separate from ITPM, which caps throughput across all requests. Tool definitions count as input on every request, plus a tool use system prompt of a few hundred tokens. Measure with the token counting endpoint.
How do I choose between Claude Haiku, Sonnet, and Opus for a custom business tool?
Test on real inputs. Anthropic positions Haiku 5.5 for high-volume classification, extraction and routing, and suggests Opus 5.5 as the general starting point. Sonnet 5.5 sits between them on price. Each model has its own rate limit, so routing routine work to a smaller model frees capacity on the larger one.
Can I set separate rate limits for different parts of my application?
Yes, with workspaces. Each has its own API keys, and you can set spend and rate limits per workspace below your organization’s. You can’t limit the default workspace, and organization-wide limits always apply. A capped workspace for background jobs protects your live tool.
Which Claude API usage tier should an SMB custom tool project start on?
Anthropic’s tiers are now named Start, Build, Scale and Custom. Organizations move up automatically based on usage history and account standing, and you can request an increase from the Console’s Rate limits page. Design for the tier you’ll start on, with caching and routing in place. Ask for more when measured peak-minute usage shows you need it.
What is the difference between a 429 and a 529 error from the Claude API?
A 429 means your organization hit one of its own limits: a rate limit, an acceleration limit or its spend cap. A 529, overloaded_error, means the API is temporarily overloaded across all users (source). Both call for backoff, but only a 429 tells you to change your own usage, tier or caching.