Claude Code Rate Limit Reached: Retry Setup for Cron Jobs

Originally published at Unattended.

"Rate limit reached" in Claude Code means one of three things. You sent too many requests or tokens per minute on the API, you used up your subscription's 5-hour or weekly allowance, or you hit a spend cap. Only the first one goes away if you retry. Anthropic's rule for that case is simple: "When the response has a retry-after header, wait that many seconds before retrying" (rate limits docs). For unattended jobs, set CLAUDE_CODE_RETRY_WATCHDOG=1 and add a wrapper that stops on quota or spend errors instead of looping on them.

Which option is right for you?

Pick the row that matches how you run Claude Code. Each row says what to do first and which page to open.

Why these picks: retrying a subscription limit or a spend cap won't work, so beginners should read the reset time first. Cron users need retries that stop on their own. Budget users get more out of a hard cap than a bigger tier.

Which Claude Code rate limit did you actually hit?

You can tell which limit you hit from the wording of the Claude Code message. Each wording has a different cause, and retrying only helps for some of them.

The Claude Code errors reference lists these message families:

At the API level, a 429 has the type rate_limit_error. It covers three cases: a rate limit, your usage tier's monthly spend cap, or a spend limit on the Claude Code workspace (API errors). A 529 overloaded_error is different. The errors reference says a 529 does not count against your quota.

The tier spend cap is the one that catches automations off guard. It comes back as a 429 with error_code: enforced_spend_limit_reached and no retry-after header. The docs warn that "Retrying, including the SDK's automatic retries, fails until access resumes" (rate limits).

How do Claude Code limits differ by plan and API tier?

Claude Code subscriptions use rolling 5-hour and weekly allowances. API keys use per-minute token buckets plus a monthly spend cap.

Subscription plans (Pro, Max, Team, Enterprise)

On Team and Enterprise, each member's usage "draws from a per-seat allowance that resets on a rolling five-hour window and a weekly window" (costs docs). That allowance is shared with Claude chat and Cowork. The same page says session and weekly limits are shared across all models, so switching models with /model only helps after an Opus- or Sonnet-specific message.

Prices (as of October 2026; check the official pricing page): Pro is $20/month, or $17/month billed annually. Max starts at $100/month. Team Standard seats are $25/month billed monthly, and Premium seats are $125/month and give "5x more usage than standard seats." The Free plan doesn't include Claude Code.

When you run out, /usage-credits lets Pro and Max subscribers keep going on usage credits. It doesn't work with API key authentication (costs docs).

API tiers (Claude Console)

API limits are counted in requests per minute (RPM), input tokens per minute (ITPM) and output tokens per minute (OTPM), separately for each model class. They are enforced with a token bucket that refills continuously (rate limits):

Three details matter for agents:

• Minute limits can be enforced over shorter intervals. The docs say "Short bursts of requests can exceed the limit and trigger rate limit errors." Five parallel subagents starting at once can trip a limit that a per-minute average says you're under.
• For most models, cached input tokens don't count toward ITPM. A good prompt cache hit rate gives you more effective throughput.
• New organizations may start in an Evaluation tier, with limits below those in the table.

If your team shares one org, Anthropic's costs page suggests 200k–300k TPM and 5–7 RPM per user for teams of 1–5 people.

How do you read Claude Code's rate-limit headers?

Every API response includes anthropic-ratelimit-* headers that show your limit, how much is left and when it refills. A 429 caused by throttling also carries retry-after.

The headers you'll check most often (rate limits):

• retry-after: seconds to wait. Earlier retries will fail.
• anthropic-ratelimit-requests-remaining and -requests-reset (an RFC 3339 timestamp)
• anthropic-ratelimit-input-tokens-remaining / -output-tokens-remaining (rounded to the nearest thousand)
• anthropic-ratelimit-tokens-*: values for whichever limit is tightest right now, including a workspace limit

To see them for your own key, print only the headers. This follows the pattern in the API errors page:

curl -sS -D - -o /dev/null 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-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}' \
  | grep -iE 'retry-after|anthropic-ratelimit'

Use this rule: a 429 with retry-after is a throttle, so wait that long. A 429 without it, plus enforced_spend_limit_reached, is a spend cap, so stop.

How do you auto-retry 429s in a headless Claude Code cron job?

Claude Code already retries transient failures 10 times with exponential backoff. For cron jobs, add the retry watchdog and a wrapper that exits cleanly when it hits a quota or spend error.

The relevant settings, from the errors reference:

Steps

1. Run claude --version and update if you're below v2.1.295. Older versions ignore the wait cap.
2. Open your job script (see /claude-code-cron-job-setup-run-automations-overnight/ for the crontab side).
3. Export CLAUDE_CODE_RETRY_WATCHDOG=1 and set a wait cap, so one stuck request can't push the job into working hours.
4. Run with -p --output-format json and save stdout to a log. The headless docs say Claude Code "exits with code 0 on success and a non-zero code when the run fails," and that failures inside the run print on stdout.
5. On a non-zero exit, check the log for quota or spend wording before you rerun anything.

Here is an example wrapper. Adjust the paths and the budget to fit your job:

#!/usr/bin/env bash
set -u
export CLAUDE_CODE_RETRY_WATCHDOG=1
export CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=1800000   # 30 min per request

LOG="$HOME/logs/nightly-$(date +%F).json"
claude -p "$(cat "$HOME/jobs/nightly.md")" \
  --output-format json \
  --max-budget-usd 5 \
  --permission-prompts none > "$LOG"
status=$?

if [ "$status" -ne 0 ]; then
  if grep -qiE "spend limit|session limit|weekly limit|credit balance" "$LOG"; then
    echo "$(date) quota/spend stop, not retrying" >> "$HOME/logs/claude-alerts.log"
    exit 2
  fi
  echo "$(date) failed with $status, see $LOG" >> "$HOME/logs/claude-alerts.log"
  exit "$status"
fi

--permission-prompts requires v2.1.259 or later. If you want live retry progress, use --output-format stream-json --verbose and watch for system/api_retry events. Each one includes attempt, max_retries, retry_delay_ms, error_status and an error category such as rate_limit or overloaded (headless docs).

If you'd rather use a hook to log or alert on failures, see /claude-code-hooks-examples-7-copy-paste-scripts/.

Limitation: the wait-and-continue-after-reset feature (v2.1.234+, set with autoContinueAtUsageLimit) is for open interactive sessions on a claude.ai subscription (errors, costs). In a -p cron run, the job ends when it hits a session limit. Schedule the next run after the reset time instead.

Common mistakes and fixes

Most repeat rate-limit failures come from retrying something that can't succeed, or from sending bursts.

• Retrying a spend cap in a loop. Your wrapper keeps firing and nothing gets through. Fix: check for enforced_spend_limit_reached or "spend limit" and exit. At the tier cap, access returns at 00:00 UTC on the first of the next month, or when you request a higher tier (rate limits).
• Expecting a self-set spend limit to return a 429. It returns HTTP 400 invalid_request_error, except on the Claude Code workspace, which can return a 429 with retry-after (rate limits).
• Starting five jobs at the same minute. Bursts trip the per-second enforcement. Fix: spread the crontab entries out (*/7, */11) or run jobs one after another.
• Using --bare with a subscription. Bare mode never reads OAuth credentials and needs ANTHROPIC_API_KEY (headless docs).
• Leaving one session open all day. Each request carries the whole conversation. Use /clear between tasks (costs). /claude-code-how-to-see-token-usage-and-reduce-it/ covers this in detail.

Why does Claude Code in VS Code say "API Error: Rate limit reached"?

The Claude Code VS Code extension runs on the same Claude Code installation and sign-in as the CLI (VS Code docs), and its usage is tracked in the same allowance (costs docs), so the causes and fixes above apply.

In the extension, open the Account & usage dialog and use the Day / Week toggle to see what used up your allowance (costs docs). If usage looks low but the error keeps coming back on an API key, check the Console's Rate limits page. A workspace limit set on the "Claude Code" workspace caps Claude Code's share of the org's rate limits, even when the org as a whole has room.

Next steps

Start with the DIY steps below, and only pay for something if they don't solve it.

Do today:

1. Run /usage and note which bar is closest to full and when it resets.
2. Add CLAUDE_CODE_RETRY_WATCHDOG=1 plus a CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS cap to your cron script, and add the spend-limit check.
3. API users: set your own limit under Billing → Spend limits → Adjust limit in the Console.

If you'd rather not manage this yourself: the main official option is more capacity. Claude Max starts at $100/month (as of October 2026; check claude.com/pricing). It suits one person who hits Pro limits on most workdays. It's a poor fit for jobs that need a guaranteed nightly throughput, because the weekly window still applies. For those, an API key on a higher tier (requested via Request tier increase on the Rate limits page) is more predictable, though you pay per token.

Related guides on this site:

• /why-claude-code-stops-mid-automation-and-how-to-fix-it/
• /claude-code-cron-job-setup-run-automations-overnight/
• /claude-code-checkpoints-how-rollback-works-in-automations/

FAQ

What does "claude code rate limit reached error" mean?

You hit one of three limits: per-minute API throttling, your plan's 5-hour or weekly allowance, or a spend cap. The message text tells you which. Only throttles and 529 overloads clear up on retry (errors).

Is "rate limit exceeded" the same as running out of my plan?

Not always. A Request rejected (429) on an API key is usually a per-minute token bucket, which refills continuously. "You've hit your session limit" is a plan allowance with a fixed reset time.

How long until a Claude Code rate limit resets?

API throttles refill continuously. The retry-after header gives the exact number of seconds. Subscription limits show the reset time in the message, and the tier spend cap resets at 00:00 UTC on the first of the next month (rate limits).

Does a 529 overloaded error use up my quota?

No. The Claude Code errors reference says a 529 is not your usage limit and doesn't count against your quota. Retry later, or switch models with /model, since capacity is tracked per model.

Sources

• Rate limits – Claude API docs
• Claude API errors
• Claude Code errors reference
• Claude Code: Manage costs effectively
• Claude Code: Run programmatically (headless)
• Claude Code: Use Claude Code in VS Code
• Claude plans and pricing
• Usage credits for paid Claude plans
• Claude status
• GEO: Generative Engine Optimization (arXiv 2311.09735)

This article was created with the help of AI. Sources are linked inline; check the official documentation for the latest details.