Troubleshooting · Claude Code

Claude Code API Error 429 (rate_limit_error) — Cause and Fix

Claude Code prints API Error: 429 rate_limit_error when the account's rate or concurrency ceiling is reached. Why parallel agents trigger it on GPT and Gemini models, and how to fix it.

What you see

API Error: 429 {"type":"error","error":{"type":"rate_limit_error","message":"Rate limit reached. Please retry shortly."}}

Why it happens

  • The rate or concurrency ceiling of the account behind your key was exceeded. Claude Code sends GPT and Gemini requests through the Messages API, and that endpoint reports the ceiling as 429 rate_limit_error.
  • Several Claude Code sessions or subagents running in parallel against the same key — each one sends a request every turn, so bursts add up faster than they look.
  • On google/* models the body text comes from the Gemini side — Resource has been exhausted. Please retry later. — while the status and error.type stay the same.
  • Retries piling on top of the burst that caused the first 429, enlarging it instead of draining it.

How to fix it

  • Wait briefly — Claude Code retries automatically and honours Retry-After. If it keeps recurring, reduce how many sessions share one key.
  • Run fewer subagents or parallel sessions at the same time — parallel requests reach the ceiling first.
  • Do not confuse this with HTTP 402 — that is empty prepaid balance. 429 is retryable throughput. Top up for 402; honour Retry-After for 429.
  • If you consistently need more throughput than the account allows, cap concurrency in your scripts and contact support. Do not retry 402 as if it were a 429.

Related searches

  • claude code api error 429
  • claude code rate limit error

FAQ

Does API Error 429 in Claude Code mean the prepaid balance is empty?+
No. A 429 is throughput. Empty prepaid balance is HTTP 402. Honour Retry-After on 429. Top up on 402.
Does Claude Code retry a 429 by itself?+
Yes — it backs off and retries automatically. If the error persists, the burst is being refilled faster than the window drains, usually by parallel sessions on the same key.
Does the model I pick in Claude Code change the 429?+
The status and error.type are the same for openai/* and google/* models. Only the text differs: GPT models say Rate limit reached. Please retry shortly.; Gemini models say Resource has been exhausted. Please retry later.

Skip the broken setup

apiToken.sale serves GPT and Gemini models through OpenAI-compatible, Messages (Anthropic format) and native Gemini endpoints — standard SDKs, one key, one prepaid balance. Point your tool's base URL at it, and the config on this page works as written.