Claude Code API error codes

429 and 529 look alike and are opposites — one is your quota, the other is Anthropic's capacity. Which codes you can fix, and which just need waiting out.

Last reviewed 2026-08-07 · verified against the pingdotgg/t3code repo

API Error 529 "Overloaded" · Retrying in 2 seconds… (attempt 9/10)
{"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}
API Error: 400 invalid_request_error
API Error: 401 authentication_error

The number is the whole message. Anthropic's API uses standard HTTP semantics, so each code points at a different layer — and two of them are routinely confused with each other.

429 vs 529: opposites that look alike#

This is the distinction worth internalising, because the wrong reading sends you to the wrong fix.

429 means you used your allowance. Your account, your plan, your usage. Reducing consumption or waiting for the window to reset helps.

529 means Anthropic is overloaded. Their servers, their capacity, everyone. Your usage is irrelevant — you can be on a Max plan with a completely fresh quota and still get 529, which is exactly what #35704 reports.

So if you're getting 529 and start auditing your token consumption, you're debugging the wrong machine.

529 Overloaded#

The service is temporarily saturated. Claude Code retries automatically — #4058 shows it working through attempt 9/10 — and when every retry fails, the load is sustained rather than momentary. #39784 and #39747 report the same.

What actually helps:

• Wait. Sounds unsatisfying, and it's correct. Capacity recovers; nothing local changes it.
• Check status.anthropic.com before assuming your setup broke. A wave of 529s across users is a platform event.
• Try a different model. Load isn't uniform across models, so a less-contended one may serve while another is saturated.
• Come back later for long runs. Starting a large refactor during sustained overload means it fails partway through, which is worse than not starting.

What doesn't help: reinstalling, re-authenticating, changing networks, clearing config. None of those touch capacity on Anthropic's side.

400 invalid_request_error#

The request was malformed. In Claude Code you rarely construct requests yourself, so a 400 usually comes from something in the session rather than something you typed:

• An oversized payload — a very large file pasted or read into context
• A malformed conversation state, which overlaps with the compaction failures where thinking blocks can't be modified
• A bad parameter from a wrapper or gateway if you're routing through a proxy or alternative endpoint

Start a clean session before anything else — it discards the accumulated state that most often causes this:

/clear

If you're pointing Claude Code at a non-Anthropic endpoint, that's the first suspect: gateways often accept a slightly different request shape.

401 authentication_error#

Your credentials were rejected: malformed, revoked, or expired.

claude auth login

If re-authenticating doesn't hold, check whether an environment variable is overriding what you just set — a stale ANTHROPIC_API_KEY in a shell profile will quietly win over an interactive login:

env | grep -i anthropic

A 401 arriving mid-session, on something that was working minutes ago, usually means a token refresh failed rather than a wrong key. That's the same family as the transport-closed auth failures.

403 permission_error#

Authentication succeeded but the credential isn't allowed to use that resource. Different from 401: you are who you say you are, you just lack access.

Common causes:

• The key belongs to an organisation or workspace without access to the model you requested
• Your plan doesn't include that model
• Workspace-level restrictions on the API key

Check your organisation's access and workspace settings in the Anthropic console. This is an account configuration question, not a client one — no amount of reinstalling Claude Code changes it.

Reading the retry line#

API Error 529 "Overloaded" · Retrying in 2 seconds… (attempt 9/10)

Two useful signals in that line:

The code tells you whether waiting can possibly help. 529 yes; 400, 401 and 403 never — retrying a malformed request or a bad credential just repeats the same failure.

The attempt counter tells you whether it's transient. Failing at 1/10 and recovering is normal operation. Exhausting 10/10 means the condition is sustained, and for 529 that means real platform load rather than a blip.

Related#

Codex has the same class of confusion with a different wrapper — there, 429, 401 and 503 all arrive inside exceeded retry limit.

FAQ#

What does API Error 529 mean in Claude Code?#

Anthropic's API is temporarily overloaded. It is not a rate limit and has nothing to do with your usage — Max subscribers with fresh quota see it too. Waiting is the fix; nothing local changes capacity.

What is the difference between 429 and 529?#

429 means you exhausted your own rate limit or quota. 529 means Anthropic's servers are saturated. They are opposites: one is about your consumption, the other is about their capacity.

How do I fix Claude Code error 401?#

Re-authenticate with claude auth login. If it recurs, check for a stale ANTHROPIC_API_KEY in your environment overriding the interactive login, using env | grep -i anthropic.

What causes a 400 invalid_request_error in Claude Code?#

A malformed request — usually an oversized payload or accumulated conversation state rather than anything you typed. Running /clear and starting fresh resolves most of them. If you route through a gateway, that's the first thing to check.

Why do I get 403 when my API key works elsewhere?#

403 is a permissions failure, not an authentication one. The key is valid but isn't allowed to use that model or resource — check your organisation and workspace access settings in the Anthropic console.

Should I retry on 529?#

Claude Code already retries automatically, up to ten attempts. If it exhausts them, the overload is sustained rather than momentary, so waiting longer is more productive than retrying immediately.