Claude Code Rate Limits: What to Do When You Hit Them

Why Claude Code gets rate limited, what the error messages mean, and five strategies to keep working when you hit the wall. Updated July 2026.

What Triggers Claude Code Rate Limits

Claude Code uses the Claude API under the hood. The rate limits you encounter depend on which access model you are using — a Max subscription plan or direct API keys.

Claude Code Max Subscription Plans

Claude Code Max plans replace per-token billing with a monthly credit pool. When the pool is exhausted, Claude Code stops accepting requests until the next billing cycle. There are two tiers:

• Max 5x ($100/month) — five times the usage of Claude Code Pro. Suited for individual developers running a moderate number of sessions.
• Max 20x ($200/month) — twenty times the Pro usage. Designed for teams or individuals operating large agent fleets with many parallel sessions.

The critical difference from API key billing: there is no per-minute cap, but once your monthly credits are gone, you are locked out for the rest of the period regardless of how much time remains. Running ten parallel agents on Max 5x exhausts credits ten times faster than running one.

Direct API Keys (Pay-As-You-Go)

If you supply an Anthropic API key directly to Claude Code instead of using a Max plan, rate limits are enforced differently — as per-minute and per-day token counts rather than a monthly pool. These limits are visible in the Anthropic Console under Usage & Limits. You can request higher limits through Anthropic support once your account has established usage history.

API key limits are typically more granular — a burst of many short requests in a short window can hit the per-minute cap even if your overall daily usage is low. This is the most common cause of rate limit errors for developers running automated agent loops.

Service-Wide Overload

Anthropic occasionally experiences high demand that affects all accounts simultaneously. These show up as “overloaded” errors that are unrelated to your plan or usage level. Always check status.anthropic.com first — if there is an active incident, waiting it out (or switching runtimes) is the only option.

Error Messages and What They Mean

Claude Code surfaces several distinct error messages when limits are hit. Each one points to a different root cause and a different fix.

The “prompt too long” error is technically not a rate limit — it is a context size constraint. But it appears alongside rate limit errors when sessions run long, because large contexts also make each API call more expensive and can push you toward per-minute token caps faster.

5 Strategies to Avoid and Handle Rate Limits

1. Multi-Runtime Fallback

The most effective immediate fix: when Claude is rate-limited, switch to Codex CLI (OpenAI) or Gemini CLI (Google). These runtimes are fully capable of handling the same coding tasks — reading files, editing code, running tests — and they pull from completely separate quota pools. If Claude hits its wall at 2 AM during an overnight run, your agent fleet does not have to stop.

amux supports all three runtimes (Claude Code, Codex, and Gemini CLI, also known as Antigravity CLI) from the same dashboard. You can reassign sessions to a different runtime without changing your task prompts or losing context from the board.

2. Context Compaction

Shorter context means fewer tokens per API call. Fewer tokens per call means lower rate-limit pressure — especially on per-minute caps for API key users. Claude Code can automatically compact (summarize) the conversation when context grows large; you can also trigger this manually with /compact.

amux auto-compacts context for sessions it manages. Beyond compaction, keeping sessions scoped to one task rather than one long multi-task session significantly reduces how much context accumulates before the task is done.

3. Stagger Session Starts

When running many agents in parallel on a Max subscription, starting them all simultaneously creates a burst of API calls in the same minute. This can push API key users past per-minute limits and causes Max plan credits to drain unevenly. Staggering session starts by 30–60 seconds spreads the load and reduces burst-related limit hits.

# amux stagger example — start sessions 30s apart
# Start first session
amux session start auth-refactor --runtime claude

# Wait 30 seconds before starting the next
# (amux scheduler can automate this spacing)
amux session start docs-update --runtime codex

4. Model Routing

Not every task requires Claude’s full capability. Routing lower-stakes work to Codex or Gemini CLI not only preserves Claude credits for tasks that genuinely need Claude’s strengths — it also reduces your total rate-limit exposure because quota pools are independent.

A practical split:

• Claude Code — complex refactors, hard debugging, architecture decisions, tasks requiring deep codebase understanding
• Codex CLI — feature scaffolding, test generation, documentation, routine file edits
• Gemini CLI — long-context tasks (Gemini has a very large context window), research, summarization across many files

5. Max Plan Upgrade

If you regularly exhaust Max 5x credits before the end of the month, the arithmetic usually favors upgrading to Max 20x rather than throttling your workflow. At $200/month for 20x usage, the per-unit credit cost is lower, and you eliminate the interruptions caused by hitting the credit wall mid-project.

Before upgrading, use amux’s Cost tab to verify that you are actually exhausting subscription credits rather than hitting a per-minute API burst limit — the fix for those two problems is different.

How amux Helps

amux is an open-source control plane for AI agent teams. It addresses rate limits at three levels: visibility, resilience, and multi-runtime routing.

Cost Tab: Real-Time Token Spend per Session

The amux dashboard’s Cost tab shows real-time token spend broken down by session. For Max plan users who have no built-in credit meter, this is the only way to see which agent is consuming the most budget before you hit the limit. For API key users, it surfaces per-session usage so you can identify which session is driving you toward the per-minute cap.

# Programmatic per-session token breakdown
curl -sk $AMUX_URL/api/observability | python3 -c "
import json, sys
data = json.load(sys.stdin)
for s in data.get('sessions', []):
    print(s['name'], '|', s.get('total_tokens', 0), 'tokens', '|', s.get('total_cost_usd', 0), 'USD')
"

Multi-Runtime Support

amux treats Claude Code, Codex CLI, and Gemini CLI as interchangeable runtimes. Sessions can be assigned to any runtime; the board, CRM, kanban, and email integrations work the same regardless of which model is driving the agent. When Claude is rate-limited, you switch the affected sessions to Codex or Gemini from the dashboard — no reconfiguration required.

Self-Healing Watchdog

amux runs a watchdog that monitors each session for overload and rate-limit errors. When a session gets an overload response, the watchdog can automatically retry after a backoff delay or mark the session for manual review on the board. This prevents silent failures where an agent appears to be running but has actually been blocked by a rate limit for hours.

Context Auto-Compaction

amux monitors context size across sessions and triggers compaction before context grows large enough to cause “prompt too long” errors or push per-call token costs up toward rate-limit thresholds. This is especially useful for overnight runs where no developer is watching the sessions.

Max 5x vs Max 20x vs API Keys: Rate Limit Behavior

Key trade-off: Max plans give predictable monthly costs but risk a hard stop if you over-run your credits. API keys have no monthly ceiling but expose you to burst-rate limits that are easy to hit with many parallel agents. Many teams use a hybrid — Max plan for primary sessions, API key accounts for overflow agents routed through Codex or Gemini CLI.

FAQ