Claude Code API Errors — 429, 401, 402, 529
Claude Code 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 per-minute throughput is exhausted. What the limit actually is, why parallel agents trigger it, and how to fix it. |
API Error: 401 {"type":"error","error":{"type":"authentication_e… | Claude Code prints API Error: 401 invalid x-api-key when the key does not reach 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 is saturated. Why it is not your request's fault, why it clusters, and what actually helps. |
API Error: 402 {"type":"error","error":{"type":"billing_error","… | Claude Code prints API Error: 402 billing_error when the prepaid balance 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 per-minute throughput is exhausted. What the limit actually is, why parallel agents trigger it, and how to fix it.
Claude Code API Error 401 invalid x-api-key — Fix
Claude Code prints API Error: 401 invalid x-api-key when the key does not reach 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 is saturated. Why it is not your request's fault, why it clusters, and what actually helps.
Claude Code API Error 402 billing_error — Insufficient Balance
Claude Code prints API Error: 402 billing_error when the prepaid balance cannot cover the request. Top up; do not retry 402 as a rate limit.