Claude Code API errors: what each message means and how to fix it

A Claude Code API error means a request to the Claude API failed after Claude Code had already retried it: it retries transient failures up to 10 times with exponential backoff before showing anything. Find your exact message below: 500 and 529 errors are on Anthropic's side, 401 and 429 point at your credential or key limits, 400 means the request itself was rejected, and codes like ECONNRESET point at your network, proxy or gateway.

Every fix here comes from Anthropic's Claude Code error reference, the Claude Platform API errors page and the network configuration docs, checked on 28 October 2026. For install, login and MCP problems, see the Claude Code troubleshooting guide. For plan limits, see Claude Code rate limits.

What does each Claude Code API error mean?

/status is the most useful command for any API error: it shows which credential Claude Code is actually using.

How does Claude Code retry before showing an error?

Claude Code retries server errors, overloaded responses, timeouts and dropped connections that happen before any of the response has streamed, plus temporary 429 throttles. While it retries, the spinner shows Retrying in Ns · attempt x/y. It does not retry TLS certificate failures, policy denials, or failures after Claude has finished a text block or tool call, because re-running could execute a tool call twice.

The error reference documents these settings:

Lower CLAUDE_CODE_MAX_RETRIES in scripts to fail faster. The environment variables guide shows where to set them.

What should you do about 529 Overloaded and 500 errors?

API Error: Repeated 529 Overloaded errors. The API is temporarily at capacity across all users. Anthropic is clear: "A 529 is not your usage limit and doesn't count against your quota." What to do:

1. Check status.claude.com for capacity notices.
2. Try again in a few minutes.
3. Run /model and pick another model, since capacity is tracked per model. Claude Code may prompt you with Opus is experiencing high load, please use /model to switch to Sonnet.

API Error: 500 Internal server error. Anthropic says a 5xx "is not caused by your prompt, settings, or account." Wait a minute and resend; for a long prompt, just type try again. If there is no posted incident and it keeps happening, run /feedback. If ANTHROPIC_BASE_URL points at a gateway and every request fails, set ENABLE_TOOL_SEARCH=false and retry.

The response above may be incomplete. A stream failed after Claude had already produced some text or a tool call, with notices like API Error: Connection lost mid-response. Claude Code keeps the completed output. Reply continue in an interactive session; in -p mode, resume the session and send continue.

Request timed out and No response from API. The default timeout is 10 minutes. Resend first. If it repeats, treat it as a network or proxy problem, and if a proxy holds responses until they finish, raise API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS.

How do you fix 401 errors and "Invalid API key"?

API Error: 401 Invalid authentication credentials. The API recognized your credential's format but rejected the account or organization behind it, so an expired token isn't the cause. Run /status:

• If it shows an active API key row, an ANTHROPIC_API_KEY is overriding your login, and /login won't replace it. Rotate the key in the Claude Console, or run unset ANTHROPIC_API_KEY to fall back to your subscription.
• If it shows only your login, run /login once.
• If the same 401 returns for the same account, the account or organization is no longer active. Ask your admin to restore access.
• Behind an LLM gateway, the text after 401 is the gateway's message, so fix the credential the gateway expects. The LLM gateway guide covers that setup.

OAuth token revoked or 401 OAuth token has expired. Your saved login is no longer valid. Run /login. For automation that can't sign in interactively, use ANTHROPIC_API_KEY or a long-lived token from claude setup-token.

Invalid API key · Fix external API key. Check the key for typos and confirm it hasn't been revoked. Run env | grep ANTHROPIC in the same shell: tools like direnv and IDE terminals can load a stale key from a project .env file without you noticing.

What does API Error 429 mean in Claude Code?

Three messages look alike but mean different things:

• API Error: Request rejected (429) is the rate limit on your API key, Amazon Bedrock project or Google Cloud project. Run /status first, because a stray ANTHROPIC_API_KEY can route a subscriber's requests through a low-tier key. Then check your provider console for limits, run fewer parallel subagents, or use a smaller model for high-volume scripted runs. Anthropic's rate limits reference explains API tiers.
• API Error: Server is temporarily limiting requests (not your usage limit) is a short throttle unrelated to your plan. It is retried automatically as of v2.1.199. Wait briefly and try again.
• Credit balance is too low means a Console organization ran out of prepaid credits, or Claude Code is using an API key when you meant to use your subscription. Subscribers should check the API key row in /status.

Subscription limits use their own wording, such as You've hit your session limit · resets 3:45pm. Those are covered in the rate limits guide.

Why does Claude Code return API Error 400?

A 400 means the API rejected the request's format or content. The fix depends on the rest of the message:

• Claude Code 2.1.219 does not support this model; version 2.1.255 or newer is required. Your version is below a minimum set per model or by your organization's policy. Run claude update (or update the desktop app) and start a new session.
• 400 due to tool use concurrency issues, orphaned tool_result or duplicate tool_use ID. The tool and thinking blocks in history no longer line up. Run /rewind, or press Esc twice, to step back to a checkpoint before the broken turn.
• context_management: Extra inputs are not permitted. Usually a gateway forwarding beta fields but dropping the anthropic-beta header. Update to v2.1.304 or later, which resends without the field, or configure the gateway to forward the header. CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 is the documented fallback. If the field named is defer_loading, set ENABLE_TOOL_SEARCH=false.
• Effort 'xhigh' isn't available with thinking turned off on this model. Run /effort high, or turn thinking back on.
• Request rejected as unprocessable by the model (too many or oversized images, or unsupported parameters). Press Esc twice to step back past the turns that added images or documents, or /clear.
• This organization has been disabled. A stale ANTHROPIC_API_KEY from a disabled Console organization is overriding your login. The troubleshooting guide walks through removing it.

What does "Prompt is too long" mean, and how do you recover?

The conversation plus attached files no longer fits the model's context window. In an interactive session it appears as Context limit reached · /compact or /clear to continue. Amazon Bedrock words the same condition Input is too long for requested model.

How to recover, from the error reference:

1. Run /compact to summarize earlier turns, or /clear to start fresh.
2. If /compact answers Not enough messages to compact., the conversation is a single exchange. Run /clear and resend with less pasted text or smaller files.
3. Run /context to see what fills the window: system prompt, tools, memory files and messages.
4. Turn off MCP servers you aren't using with /mcp disable <name>, and trim large CLAUDE.md files.
5. Turn auto-compact back on in /config if you switched it off; it normally prevents this error.

If the error appears near 200K tokens on a model that accepts more, Claude Code may not recognize your model ID and is assuming a 200K window; the docs explain how to set the real one. A separate error, Request too large (max 32MB), is about raw request size, usually from images. /compact drops accumulated attachments. The compact guide explains compaction in detail.

How do you fix "Unable to connect to API", ECONNRESET and timeouts?

These mean the connection to the API failed or never completed. Since v2.1.227 the message names the kind of failure, for example Connection dropped (ECONNRESET) or Can't reach the API server, with ENOTFOUND in parentheses. Work through the documented checks:

curl -I https://api.anthropic.com
echo $ANTHROPIC_BASE_URL

• If curl fails, check your internet connection, VPN and DNS. Behind a corporate proxy, set HTTPS_PROXY before launching Claude Code.
• If curl works but Claude Code still fails, look for a leftover ANTHROPIC_BASE_URL pointing at a local proxy or gateway that isn't running. That produces Connection refused even though the API is reachable.
• If every request through a gateway ends in Connection dropped, set ENABLE_TOOL_SEARCH=false and try again.
• On Linux and WSL, check /etc/resolv.conf for an unreachable nameserver. On macOS, a removed VPN can leave stale utun interfaces behind.

Certificate errors. SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY) or SELF_SIGNED_CERT_IN_CHAIN means a proxy is re-signing traffic. Point Claude Code at your company's CA bundle with NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem. Anthropic says not to set NODE_TLS_REJECT_UNAUTHORIZED=0, which turns off certificate checks entirely.

When should you check status.claude.com or report a bug?

Check status.claude.com first for any 500, 529 or repeated timeout, since those are server-side. If there's no incident and the error keeps coming back:

1. Run /feedback in Claude Code to send the report to Anthropic.
2. Search or open an issue in the Claude Code GitHub repository with your version (claude --version), provider and the full error text.
3. For direct API integrations, include the request_id from the error body, which Anthropic's API docs say helps support find the request.

When an error keeps returning, a saved diagnosis prompt helps. Kipt keeps prompts as Markdown in a private GitHub repo you own, so a prompt with an {{error_message}} blank that asks Claude to explain an error and propose a fix is a Cmd+K search away.