Claude API 429 Error Troubleshooting and Fix Guide

A 429 error from the Claude API means you've exceeded a rate limit: too many requests in a given time window, too many tokens processed per minute, or too many concurrent requests for your account tier. It's not a bug in your code — it's Anthropic (or whichever gateway you're calling through) telling you to slow down or spread out your traffic.

The fix depends on which limit you hit, but the general approach is always the same: read the response headers to understand which limit you crossed, implement exponential backoff with jitter, and if you're hitting limits regularly in production, either request a quota increase, batch your requests more efficiently, or spread load across multiple keys/accounts. Below is a practical walkthrough.

Why you're getting a 429

Claude API rate limits are typically enforced across three dimensions:

• Requests per minute (RPM) — total number of API calls, regardless of size
• Tokens per minute (TPM) — input + output tokens processed, often split into separate input/output limits
• Concurrent requests — how many requests can be in flight at once, relevant for streaming and long-running completions

Your limits are tied to your usage tier, which usually increases automatically as your account has a longer billing history and higher spend. A fresh account or a low tier will hit 429s much faster than an established one, even with modest traffic.

Common causes in real applications:

1. A burst of requests fired in parallel (e.g., processing a batch of 100 documents with Promise.all)
2. A retry loop that retries immediately without backoff, compounding the problem
3. Large prompts (long context, big system prompts) that consume your TPM budget fast even at low RPM
4. Multiple services or team members sharing one API key without coordinated throttling
5. A spike in end-user traffic that wasn't load-tested against your configured limits

Read the response headers first

Before you write any retry logic, inspect the actual 429 response. Anthropic's API returns headers indicating your current limit status:

curl -i https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":1024,"messages":[{"role":"user","content":"hi"}]}'

Look for headers like:

anthropic-ratelimit-requests-limit: 50
anthropic-ratelimit-requests-remaining: 0
anthropic-ratelimit-requests-reset: 2024-01-15T10:32:00Z
anthropic-ratelimit-tokens-limit: 40000
anthropic-ratelimit-tokens-remaining: 1200
retry-after: 12

The retry-after header (in seconds) is the single most useful signal — it tells you exactly how long to wait before retrying, rather than guessing.

Fix 1: implement exponential backoff with jitter

Never retry a 429 immediately. Use exponential backoff with randomized jitter so multiple concurrent requests don't all retry at the same instant and re-trigger the limit.

async function callWithBackoff(fn, maxRetries = 5) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status !== 429 || attempt === maxRetries) throw err;

      const retryAfter = err.headers?.get("retry-after");
      const baseDelay = retryAfter
        ? parseInt(retryAfter, 10) * 1000
        : Math.min(1000 * 2 ** attempt, 30000);
      const jitter = Math.random() * 500;

      await new Promise((r) => setTimeout(r, baseDelay + jitter));
    }
  }
}

This pattern alone resolves the majority of transient 429s caused by short traffic bursts.

Fix 2: throttle concurrency at the source

Backoff handles occasional spikes, but if you're regularly firing dozens of parallel requests (batch processing, bulk summarization, etc.), you need a concurrency limiter so you never exceed your RPM/TPM budget in the first place.

import pLimit from "p-limit";

const limit = pLimit(5); // max 5 concurrent Claude calls

const results = await Promise.all(
  documents.map((doc) => limit(() => summarize(doc)))
);

Tune the concurrency number against your actual tier limits, not a guess. If your TPM limit is 40,000 and each request uses ~4,000 tokens, five concurrent requests at ~1 second each roughly saturates your budget — going higher just produces more 429s and wasted retries.

Fix 3: queue and rate-limit at the application layer

For production systems with unpredictable user traffic, a token-bucket or leaky-bucket queue in front of your Claude calls is more robust than ad hoc retries. Accept requests into a queue, drain them at a fixed rate matching your RPM/TPM ceiling, and return results asynchronously (via webhook, polling, or websocket) rather than making the end user's request wait on a synchronous call that might 429.

Fix 4: reduce token usage per request

If you're hitting TPM limits specifically (remaining tokens near zero while requests remaining is healthy), the fix isn't more retries — it's using fewer tokens:

• Trim system prompts and remove redundant instructions
• Summarize or truncate long conversation history instead of resending full context every turn
• Cache static context where supported instead of resending it on every call
• Use a smaller/faster model for steps that don't need the most capable one

Fix 5: increase your limits or split traffic

If you've optimized concurrency and token usage and are still hitting 429s consistently in production, request a tier/limit increase from Anthropic based on your sustained usage, or split traffic across multiple API keys/projects if your workload is naturally partitionable (e.g., per-customer isolation).

If you're building a product on top of Claude and want rate-limit handling, retries, and usage visibility handled for you rather than building it yourself, SubToAPI (/signup) gives you an HTTPS API with streaming (/docs/streaming), tool use (/docs/tools), and per-key usage metadata so you can see exactly which application key is consuming your quota before it turns into a 429. Plans start at €9/month — see /pricing. The quickstart at /docs/quickstart walks through generating a sub_live_... key and making your first request against /docs/messages.

Questions

Does a 429 mean my API key is broken or revoked? No. A 429 is purely a rate-limit response — your key is valid, you've just exceeded requests, tokens, or concurrency allowed in the current window. A revoked or invalid key returns a 401, not a 429.

Should I retry a 429 immediately? No. Immediate retries often make the problem worse by adding more load into the same limited window. Use the retry-after header if present, otherwise exponential backoff with jitter starting around 1 second.

Will upgrading my plan automatically fix 429 errors? It can help if the root cause is a hard ceiling on requests or tokens per minute, but if the real issue is unthrottled concurrency or inefficient prompts, fix those first — a higher limit just delays the same problem at larger scale.