Claude API Rate Limits & Error Handling: A Production Guide

The Claude API enforces limits along more than one dimension — requests per minute and token throughput both matter, and token limits are usually the one production systems hit first, because long prompts and generous max_tokens settings consume budget far faster than request counts suggest. Limits vary by usage tier: as your organisation’s usage and spend history grow, higher tiers unlock more headroom. The exact numbers change and differ per model, so treat them as configuration to read from Anthropic’s documentation and your console, never as constants in code.

Architectural implications worth internalising early:

• Budget capacity per model — limits are not one global pool.
• Estimate token consumption per request class; that is your real capacity plan.
• Design for throttling on day one, because success means meeting your limits eventually.
• Plan tier upgrades ahead of launches, not during them.

Production error handling starts with classification, because the correct response differs by class. 429 (rate limited): back off and retry — the response includes a retry-after header telling you how long to wait; honour it rather than guessing. 529 or overloaded errors: the service is under transient load; retry with backoff exactly as for 429s. 500-class server errors: retry a small number of times, then fail over or degrade. 400 (invalid request): never retry — the request is malformed, and retrying identical bad input just burns quota; log it and fix the bug. 401/403: credential or permission problems; escalate immediately, no retry will help. Context or token errors: your prompt outgrew the window — trim, summarise, or restructure.

Encode this taxonomy in one shared client wrapper so every service in your organisation behaves identically. Scattered ad-hoc handling is how one team’s retry bug exhausts everyone’s shared quota.

The standard remedy for 429s is exponential backoff with jitter, and both halves matter. Exponential growth spaces out retries; jitter — randomising each delay — prevents a fleet of clients from retrying in synchronised waves that recreate the spike they are recovering from.

async function withBackoff(fn, max = 5) {
  for (let i = 0; i < max; i++) {
    try { return await fn(); }
    catch (e) {
      if (e.status !== 429 && e.status < 500) throw e;
      const hinted = e.headers?.["retry-after"] * 1000;
      const delay = hinted || Math.random() * 1000 * 2 ** i;
      await sleep(delay);
    }
  }
  throw new Error("retries exhausted");
}

Note the priority order: an explicit retry-after hint beats your computed delay. Cap total retry duration so callers fail fast enough to degrade gracefully, and surface retry counts as metrics — rising retries are your earliest capacity warning.

Backoff is reactive; queuing is preventive. Instead of letting every service call the API directly and collide, route requests through a queue with a concurrency limiter that releases work at a rate your tier can sustain. This converts bursty demand into smooth throughput and gives you a natural place for prioritisation — interactive user requests jump the queue, background enrichment jobs wait.

Design decisions that matter in practice:

• Centralise the limiter. A per-process semaphore fails once you scale horizontally; use a shared token bucket (Redis or your gateway) so all instances draw from one budget.
• Bound the queue. Unbounded queues turn overload into latency nobody asked for; shed or defer low-priority work instead.
• Separate pools per model and per priority class, mirroring how limits are actually enforced.
• Make queue depth and wait time first-class metrics — they predict user-visible latency before it happens.

The cheapest request is the one that consumes fewer tokens, and two platform features attack demand directly. Prompt caching lets you mark stable prompt prefixes — system prompts, tool definitions, shared reference documents — so repeated requests reuse them at a fraction of the cost and latency of reprocessing. For chat products and agent loops that resend context every turn, caching routinely becomes the single largest efficiency win, and lighter requests stretch the same rate limit further.

The batch API handles the other half of your traffic: anything that does not need an answer in seconds. Nightly document classification, bulk summarisation, evaluation runs, and re-indexing jobs belong in batches, which process asynchronously at reduced cost and — crucially — outside your interactive rate budget. A simple triage rule works well: if no human is waiting on the response, it should probably be a batch. Our Claude API & MCP training works through both features with production exercises.