Claude Code API Errors — 429, 401, 402, 529
Claude Code talks to GPT and Gemini models here through the Messages API, and it surfaces API failures as a single line starting with "API Error:" followed by the raw response body. The pages below cover each form with the exact text, why it happens, and what fixes it.
| Error | Meaning |
|---|---|
API Error: 429 {"type":"error","error":{"type":"rate_limit_error… | 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. |
API Error: 401 {"type":"error","error":{"type":"authentication_e… | Claude Code prints API Error: 401 authentication_error when no valid key reaches the endpoint it is talking to. The environment-variable rules that cause it and the fix. |
API Error: 529 {"type":"error","error":{"type":"overloaded_error… | Claude Code prints API Error: 529 Overloaded when upstream capacity for the selected GPT or Gemini model is saturated. Why it is not your request's fault, why it clusters, and what actually helps. |
API Error: 402 {"type":"error","error":{"type":"invalid_request_… | Claude Code prints API Error: 402 when the prepaid balance or the key's spending limit cannot cover the request. Top up; do not retry 402 as a rate limit. |
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.
Claude Code API Error 401 authentication_error — Fix
Claude Code prints API Error: 401 authentication_error when no valid key reaches the endpoint it is talking to. The environment-variable rules that cause it and the fix.
Claude Code API Error 529 Overloaded — What It Means
Claude Code prints API Error: 529 Overloaded when upstream capacity for the selected GPT or Gemini model is saturated. Why it is not your request's fault, why it clusters, and what actually helps.
Claude Code API Error 402 — Insufficient Balance
Claude Code prints API Error: 402 when the prepaid balance or the key's spending limit cannot cover the request. Top up; do not retry 402 as a rate limit.