Claude API Token Limits: Tiers, TPM Caps, and Managing Large Payloads

As documented in Anthropic's upload guidelines, individual chats accept up to 20 files at up to 500MB each, while projects accept files up to 30MB each with an unlimited file count as long as total content fits within Claude's context window. Yet developers sending unstructured data to the Messages API immediately encounter a 200,000 input token per-request ceiling and organization-level throughput caps. Many engineering teams run into unexpected errors because technical guides frequently conflate consumer chat upload allowances with developer API rate limits.

Claude API token limits define the maximum tokens per minute (TPM) and tokens per day (TPD) permitted across Anthropic developer account tiers. When developers read that Claude can analyze 500MB files, they often assume the underlying REST API accepts identical payloads over raw HTTP calls. In practice, the consumer web client, Claude Projects, and the developer Messages API operate under three distinct ingestion architectures.

Consumer Chat Attachments Versus Messages API Payloads

In the Claude web and mobile chat interfaces, users can attach documents and images directly into a discussion thread. According to Anthropic's documentation on uploading files to Claude, individual chat conversations support up to 20 files per chat, with a maximum file size of 500MB per file. When working within Claude Projects, individual uploaded files are limited to 30MB each. Claude Projects has no fixed file-count cap; the total content of all project files is constrained only by Claude's context window.

The Claude Messages API does not operate as a direct binary storage endpoint. When sending content to the API endpoint (https://api.anthropic.com/v1/messages), documents must be extracted into text strings or encoded as supported image blocks within the request body. Every character of text and every image pixel is converted into tokens before processing begins. A 40MB PDF document containing dense financial tables can translate into hundreds of thousands of tokens, surpassing per-request constraints long before hitting transport-level byte caps.

The 200,000 Token Per-Request Context Ceiling

Across current Claude models, including Claude 3.5 Sonnet, Claude 3.7 Sonnet, Claude 3 Opus, Claude 3.5 Haiku, and Claude 3 Haiku, Anthropic maintains a standard context window limit of 200,000 input tokens per request. Output generation per single call is capped separately, typically at 4,096 or 8,192 tokens depending on the chosen model.

While a 200,000 token context window accommodates roughly 150,000 words of English prose, attempting to use the full window on every API call introduces severe operational penalties:

• Latency degradation: Time to first token increases linearly with prompt length. Processing a 180,000 token prompt can require several seconds of prefill computation before generation begins.
• Inference costs: Input tokens are billed on every request unless cached. Repeatedly transmitting multi-megabyte payloads creates substantial billing overhead.
• Throughput exhaustion: Organization-level rate limits restrict how many tokens can be consumed within rolling 60-second windows. A single request carrying 180,000 tokens can instantly exhaust an entire minute of allocated token throughput on entry developer tiers.

• OpenAI Codex Usage Limits: API Tiers, Rate Caps, and Token BudgetsOpenAI Codex usage limits are tier-based rate caps (requests per minute and tokens per minute) and monthly spending...
• How to Handle Claude Code Token Limits in Large ProjectsClaude Code enforces a 200,000-token context window that fills quickly on complex repositories as file reads and bash...
• Claude 5-Hour Limit Explained: Reset Rules, Token Consumption, and WorkaroundsThe Claude 5 hour limit is Anthropic's rolling rate-limiting mechanism that dynamically restricts user message volume...
• Claude Daily Limit: Usage Caps, Reset Times, and WorkaroundsClaude daily limits refer to the message and token caps imposed on Claude.ai accounts, which operate as fixed 24-hour...
• Claude Code Rate Limits: 5-Hour Usage Caps, 429 Errors, and WorkaroundsClaude Code rate limits enforce execution thresholds across terminal requests, tokens per minute, and five-hour rolling...
• Claude CSV File Limit: Token Caps, File Limits, and Data WorkaroundsThe Claude CSV file limit allows uploads up to 30MB in Projects or 500MB in individual chats, but tabular datasets are...

More on this subject: Claude and Claude Code (326 guides)

As detailed in the Anthropic rate limits documentation, the Messages API enforces throughput limits at the organization level rather than per API key or per user account. These limits govern three core metrics simultaneously: Requests Per Minute (RPM), Input Tokens Per Minute (ITPM), and Output Tokens Per Minute (OTPM).

Understanding these caps requires examining both the legacy numerical tier structure and the modern named usage tiers established by Anthropic.

Developer Tier Thresholds: Start, Build, and Scale

Historically, developer accounts progressed through numerical tiers based on cumulative prepaid account deposits:

Anthropic restructured developer accounts into named usage tiers: Start, Build, Scale, and Custom. New organizations with no payment history begin in an initial Evaluation tier, which maintains strict starter limits to prevent platform abuse while billing history is verified.

The following comparison table outlines the standard Anthropic developer API tiers, monthly spend caps, and model throughput thresholds:

On accounts using Claude Platform on AWS, billing operates through AWS Marketplace invoices rather than Anthropic credit purchases. AWS-linked organizations start on the Start tier and scale automatically as monthly invoice history accumulates.

The Token Bucket Algorithm and Sub-Minute Rate Smoothing

Anthropic evaluates throughput using the token bucket algorithm rather than fixed 60-second clock windows. Instead of granting a pool of tokens that suddenly replenishes at the top of each clock minute, your organization's token bucket continuously refills at a fixed rate per second up to the tier maximum.

This architecture introduces sub-minute rate smoothing. If your tier provides a limit of 1,200 RPM, the API evaluates this capacity smoothly as approximately 20 requests per second. Dispatching 60 parallel requests inside a single 200-millisecond burst will instantly empty your available token bucket. The server responds with HTTP 429 errors, even though your total traffic for the rolling 60-second window is well below the published 1,200 request ceiling.

Similarly, ITPM limits are evaluated per request. If your tier ceiling is 1,000,000 ITPM and you fire six concurrent requests each containing 180,000 tokens within two seconds, total instantaneous consumption reaches 1,080,000 input tokens. The sixth request will be rejected immediately because it exceeds available bucket depth.

When an application exceeds an RPM, ITPM, or OTPM threshold, the Anthropic Messages API returns an HTTP 429 Too Many Requests status code. Handling this error correctly in production software requires distinguishing between rolling throughput exhaustion and account-level spend caps.

Interpreting HTTP 429 Errors and Rate Limit Headers

Anthropic returns two distinct varieties of HTTP 429 responses:

1. Rolling Rate Limit Errors: Triggered when request velocity or token volume exceeds the active bucket capacity. The response body returns error.type: "rate_limit_error". Crucially, the response headers include a retry-after header stating the exact number of seconds the client must wait before retrying the call.
2. Enforced Spend Limit Errors: Triggered when the organization crosses its monthly account spend cap. The response returns error.type: "rate_limit_error", but the inner details specify error.details.error_code: "enforced_spend_limit_reached". This error does not include a retry-after header. Retrying the request with programmatic backoff will fail repeatedly because all API calls remain blocked until 00:00 UTC on the first day of the following calendar month, unless an administrator manually increases the monthly spend cap in the Claude Console.

Every successful API response includes tracking headers that allow clients to monitor their available rate limit headroom in real time:

anthropic-ratelimit-requests-limit: 1000
anthropic-ratelimit-requests-remaining: 985
anthropic-ratelimit-requests-reset: 2026-11-07T12:00:00Z
anthropic-ratelimit-input-tokens-limit: 2000000
anthropic-ratelimit-input-tokens-remaining: 1845200
anthropic-ratelimit-input-tokens-reset: 2026-11-07T12:00:00Z
anthropic-ratelimit-output-tokens-limit: 400000
anthropic-ratelimit-output-tokens-remaining: 392100
anthropic-ratelimit-output-tokens-reset: 2026-11-07T12:00:00Z

Monitoring anthropic-ratelimit-input-tokens-remaining in an application middleware layer allows you to throttle concurrent workers proactively before hitting hard 429 rejections.

Implementing Client-Side Backoff and Retry Jitter

Production applications should never retry failed requests immediately in a tight loop. When multiple workers encounter rate limits simultaneously, immediate retries cause a thundering herd problem that repeatedly hammers the API and extends the lockout window.

The recommended strategy combines exponential backoff with full randomization jitter, respecting the server's retry-after header whenever present:

import random
import time
import anthropic

client = anthropic.Anthropic()

def execute_message_with_retry(messages, model="claude-3-5-sonnet-20241022", max_retries=5):
    base_delay = 1.0
    max_delay = 60.0
    for attempt in range(max_retries):
        try:
            response = client.messages.create(
                model=model,
                max_tokens=1024,
                messages=messages,
            )
            return response
        except anthropic.RateLimitError as exc:
            if attempt == max_retries - 1:
                raise
            retry_after_header = getattr(exc.response, "headers", {}).get("retry-after")
            if retry_after_header:
                sleep_duration = float(retry_after_header)
            else:
                jitter = random.uniform(0.5, 1.5)
                sleep_duration = min(max_delay, (base_delay * (2 ** attempt))) * jitter
            time.sleep(sleep_duration)
    raise RuntimeError("Exceeded maximum rate limit retry attempts")

When handling batch operations with high concurrency, configure a client-side token bucket or leaky bucket queue in your task runner to match your organization's published RPM and ITPM constraints.

Query massive document libraries without hitting API token caps

Store and auto-index gigabytes of files in a shared workspace, then let Claude search relevant excerpts via MCP rather than loading entire libraries into prompt payloads. Starts with a 14-day free trial.

Start 14-Day Trial

Scaling Claude API workflows without repeatedly triggering rate limits requires careful prompt payload design. Developers can maximize effective throughput within existing tier ceilings by adopting prompt caching, using the Message Batches API, and avoiding full document serialization in chat turns.

Multiplying Throughput with Prompt Caching

Anthropic implements cache-aware ITPM accounting on Claude 3.5 Sonnet, Claude 3.5 Haiku, and Claude 3 Opus. Understanding how cache reads are evaluated against your token bucket is one of the most effective levers for scaling throughput without requesting an account tier increase.

When sending a request, the API divides input tokens into three categories:

• input_tokens: Uncached input tokens that appear after the final cache breakpoint. These count toward your ITPM rate limit.
• cache_creation_input_tokens: Tokens written to the cache during an initial request. These count toward your ITPM rate limit.
• cache_read_input_tokens: Tokens retrieved from cache on subsequent calls. These do not count toward your active ITPM rate limit.

Because cache reads do not draw down your per-minute token bucket, prompt caching multiplies your effective throughput. Consider an organization operating under a 2,000,000 ITPM limit. If an application repeatedly queries a 160,000 token legal code or codebase reference, sending that document raw across 15 requests per minute would consume 2,400,000 input tokens and trigger immediate rate limit errors.

By placing a cache breakpoint ("cache_control": {"type": "ephemeral"}) on the large reference block, the initial call writes the 160,000 tokens to cache. Subsequent calls read directly from memory. Each follow-up request only consumes the 200 tokens needed for the user's specific question against the active ITPM bucket. The organization can process dozens of queries per minute while consuming only a tiny fraction of its token ceiling.

Asynchronous Processing with the Message Batches API

For workloads that do not require real-time streaming responses, such as processing invoice backlogs, auditing repositories, or evaluating benchmark datasets, Anthropic provides the Message Batches API.

The Message Batches API offers two critical advantages for high-volume data processing:

• Independent Rate Quotas: Batch requests do not consume from your interactive RPM, ITPM, or OTPM buckets. They run in a dedicated asynchronous background processing pool, protecting your production conversational interfaces from starvation.
• Cost Efficiency: Message Batches bill all input and output tokens at half the standard pricing of interactive Messages API calls.

Batches accept up to 10,000 requests or 32MB of payload data per batch call, returning results asynchronously within a 24-hour turnaround window.

Pruning Conversational Context and Truncating Payloads

Multi-turn chat agents frequently accumulate conversation history indefinitely, re-transmitting every previous user prompt, tool call, and tool result with every new turn. In an agent workflow spanning 25 tool interactions, the cumulative payload sent to the API can grow from 2,000 tokens on turn one to over 80,000 tokens on turn twenty.

To prevent conversational context from overwhelming your per-minute token budget:

• Summarize completed turns: Replace older intermediate tool results with structured state summaries once the agent has extracted the necessary facts.
• Drop bulky scratchpad outputs: If a bash command or code execution tool generates 500 lines of terminal logs, parse the return value and transmit only the relevant error message or exit code back to Claude.
• Isolate tool schemas: Do not declare dozens of unused tool schemas in the tools array of every API call. Provide only the tools relevant to the active operational phase. Review the agent onboarding guide for patterns on structuring lean agent prompts.

When applications need to analyze large document collections, developers face an architectural choice: transmit entire files directly within prompt payloads or decouple storage from the model's context window through an external retrieval layer.

The High Cost of In-Prompt Document Stuffing

Attempting to solve enterprise document search by stuffing raw files into the Claude API request payload quickly hits practical barriers. When an application needs to evaluate a portfolio of 40 contracts, hundreds of customer tickets, or a technical manual spanning thousands of pages, the combined corpus can easily exceed tens of millions of tokens.

Even if individual files fit within the 200,000 input token context window, stuffing entire documents into every prompt creates severe bottlenecks:

• Rapid TPM Exhaustion: A team on the Start tier with a 1,000,000 ITPM limit can process only five requests per minute if each request carries 180,000 tokens of documentation.
• Attention and Extraction Latency: While Claude exhibits strong needle-in-a-haystack retrieval across long contexts, searching through 190,000 tokens of unindexed text for a single paragraph introduces latency penalties on every interaction.
• Cost Accumulation: Transmitting the same static documents repeatedly without caching incurs continuous per-token billing charges.

Teams frequently attempt to address this by building custom retrieval pipelines using Amazon S3 or Google Drive connected to dedicated vector databases such as Chroma, Pinecone, or pgvector. However, custom retrieval infrastructure requires ongoing engineering maintenance: developing document parsers for complex PDFs and spreadsheets, configuring chunking strategies, generating and storing vector embeddings, and building synchronization scripts to update vector indexes whenever underlying files change.

Offloading Large Corpora to an MCP-Connected Workspace

A more durable pattern places the document corpus into an intelligent workspace and allows Claude to query specific excerpts on demand via the Model Context Protocol (MCP).

Fast.io provides shared, organization-owned cloud workspaces designed for collaboration between human teams and AI agents. Rather than packing hundreds of pages into prompt payloads, teams store their documents directly in a workspace backed by Fast.io persistent storage for AI agents.

Once Intelligence Mode is enabled on the workspace, Fast.io automatically indexes all stored files for hybrid search, combining full-text keyword matching, semantic vectors, and metadata extraction. Claude connects to the workspace through Fast.io's remote MCP server at https://mcp.fast.io/mcp/tools, documented in the Fast.io MCP setup guide.

Claude Desktop / Web / Agent
           │
           ▼ (MCP Streamable HTTP)
https://mcp.fast.io/mcp/tools
           │
           ▼
Fast.io Intelligent Workspace
(Auto-indexed files, hybrid search, citations)

When Claude needs information to answer a user inquiry, it does not receive the raw 50MB PDF in its prompt. Instead, Claude issues an MCP search action to the workspace. Fast.io searches the indexed corpus and returns only the precise paragraphs and data points relevant to the query, accompanied by document citations.

This architecture delivers substantial operational benefits:

• Tiny API Prompt Footprint: The initial prompt sent to the Claude API contains only the user query and tool definitions, often totaling fewer than 1,000 tokens. The returned context adds only 500 to 2,000 tokens of relevant excerpts.
• Preserved Rate Limit Headroom: Because requests consume minimal token capacity, applications can handle high concurrency without triggering HTTP 429 rate limits.
• Multi-Cloud Synchronization: Teams do not need to migrate existing file systems manually. Fast.io Cloud Sync connects Google Drive, Dropbox, Box, and OneDrive folders to a workspace, one-way or two-way, on a schedule or on demand. Existing shared drives are indexed automatically for Claude.
• Structured Extraction with Metadata Views: For tabular document analysis, Fast.io Metadata Views turn unstructured documents into queryable spreadsheets. Natural language field descriptions generate typed schemas (Text, Integer, Decimal, Boolean, URL, JSON, Date & Time), allowing Claude to query structured records without parsing raw text.

Fast.io plans scale with team and agent requirements. Monthly plans start with a 14-day free trial, which requires a credit card. Plans are Starter at $9.99/mo (3 seats, 250 GB storage, 5 workspaces, 100,000 credits a month), Business at $49.99/mo (10 seats, 5 TB storage, 50 workspaces, 600,000 credits a month), and Enterprise at $199.99/mo (30 seats included, more at $1 a seat up to 200, 25 TB storage, 200 workspaces, 3,000,000 credits a month). Annual plan pricing options are $99, $499, and $1,999 a year. Credits meter AI operations with overage at $10 per 100,000 credits, while storage beyond plan allowances is billed at 1.5 cents per GB a month. Maximum upload size is 25 GB on Starter, 50 GB on Business, and 100 GB on Enterprise. Detailed pricing tiers are listed on the Fast.io pricing page.

Connecting Claude to a Fast.io workspace via MCP leaves Anthropic's upload limits intact while providing a searchable, persistent repository for files that exceed prompt token boundaries.