Claude Code Rate Limit & Usage Limit — How to Fix It

Before assuming you hit your own cap, confirm Anthropic itself is healthy. During an incident, error messaging can be misleading and a retry a few minutes later may simply work.

This is the step everyone skips — and it decides the fix. Run /status inside Claude Code to see how you are authenticated, then read the wording of the limit message:

# Inside Claude Code
/status     # shows your account, auth method (subscription vs API key), and model

• Signed in with a Claude Pro / Max account, and the message mentions a usage limit or a reset time → you are on a subscription limit (go to step 3).
• Using an ANTHROPIC_API_KEY, and the message mentions rate limit or 429 → you are on an API rate limit (go to step 5).
• Not sure which key is active? /status and your shell’s echo $ANTHROPIC_API_KEY tell you whether an API key is set in the environment.

On Pro or Max, the limit is a rolling time window, not a balance you can top up. Your options, in order:

• Wait for the window to reset. The message usually states when. A short window recovers in a few hours; a weekly cap (Max) recovers when the week rolls over.
• Upgrade Pro → Max for materially higher caps. Note this raises future windows — a window you have already exhausted still resets on its own clock, so upgrading is not an instant unblock.
• Spread heavy work out. Break large refactors or codebase-wide tasks into batches across windows instead of one marathon session that drains the window in minutes.
• Need headroom right now? Switch Claude Code to an Anthropic API key (pay-as-you-go). You will be billed per token, but you are no longer bound to the subscription window — then step 5 applies instead.

Exact window lengths and amounts change over time and by plan, so treat the reset time in the message as authoritative rather than any fixed number you read online.

Whichever limit you are on, a bloated context is what drains it fastest — every turn re-sends the whole conversation. Trim it and each request costs less:

# Inside Claude Code
/compact                 # summarize & shrink the running conversation context
/clear                   # start fresh when the task changes entirely
@src/only/what/i/need.ts # scope @-file context tightly, not whole folders

• Run /compact often on long sessions — it replaces a huge transcript with a summary so later turns carry far fewer tokens.
• Scope @-file context tightly. Attach the specific files you need, not entire directories, and avoid re-reading large files you have already seen.
• Prefer a lighter model for routine or mechanical steps and reserve the heaviest model for the hard reasoning — big contexts on a big model eat the limit fastest.
• Avoid dumping build logs or huge JSON into the chat; point Claude at a file or a filtered command instead.

If /status shows an API key and you are seeing 429, you have hit requests-per-minute or tokens-per-minute for your usage tier. Two levers:

• Raise your usage tier. Tiers unlock with historical spend and grant higher per-minute limits. Check yours at console.anthropic.com/settings/limits.
• Let backoff do its job. Claude Code and the official SDKs already retry 429 with exponential backoff. You mostly just need to not fight it.

For your own scripts that call the Anthropic API directly (outside Claude Code), add explicit exponential backoff with jitter so a burst of 429s does not fail the whole job:

// Node — retry Claude API 429 rate limits with exponential backoff
import Anthropic, { APIError } from '@anthropic-ai/sdk';

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

async function withBackoff(fn, maxAttempts = 6) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (e) {
      const retriable = e instanceof APIError && (e.status === 429 || e.status === 529);
      if (!retriable || attempt === maxAttempts - 1) throw e;
      const wait = Math.min(60_000, 2 ** attempt * 1000 + Math.random() * 1000);
      console.warn(`Claude API ${e.status} — retry ${attempt + 1} in ${(wait / 1000).toFixed(1)}s`);
      await new Promise(r => setTimeout(r, wait));
    }
  }
}

// Usage
const msg = await withBackoff(() => client.messages.create({
  model: 'claude-3-5-haiku-20241022',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello' }],
}));