Rate limits & error handling

Rate limits are enforced caps on how many API requests and tokens an organization can process within a given time window. Anthropic measures them across three dimensions: Requests Per Minute (RPM), Input Tokens Per Minute (ITPM), and Output Tokens Per Minute (OTPM). Limits are applied at the organization level, with optional workspace-level sub-limits configurable by administrators. The API uses a token bucket algorithm, meaning capacity refills continuously rather than resetting at fixed clock intervals. When any limit is exceeded, the API returns an HTTP 429 error with a machine-readable JSON body identifying which limit was breached, plus a `retry-after` header specifying how many seconds to wait before retrying. Other relevant error codes include 500 (api_error), 504 (timeout_error), and 529 (overloaded_error). For streaming responses delivered over SSE, errors can surface after an initial 200 OK, so error handling must cover the entire stream lifetime, not just the connection phase. Organizations advance through usage tiers (Tier 1 through Tier 4) automatically as cumulative spend increases, unlocking higher RPM, ITPM, and OTPM ceilings at each level. Prompt caching provides an effective throughput multiplier because, on most models, only uncached input tokens count toward the ITPM limit. Specialized endpoints such as the Message Batches API, Fast Mode, and Claude Managed Agents maintain separate rate limit pools distinct from the standard Messages API.