When a red error message pops up in Claude Code, it can be alarming. But most errors have well-defined causes, and you can fix them yourself just by reading the message calmly. This article explains, for first-timers, how to read an error message, figure out what kind it is, and what to do.
First: errors appear only "after several retries already happened"
The most important fact first. Claude Code automatically retries transient problems (server congestion, slow responses, dropped connections). Per the official docs, it retries up to 10 times in these cases, showing a Retrying in Ns · attempt x/y countdown meanwhile.
In other words, the error you see appears only after the automatic retries have all failed. So don't panic — start by simply reading the message.
Errors fall into 5 broad kinds
When you see an error, first sort "is this my problem or the server's?" The official docs group errors roughly into these five.
① Server errors (not your fault)
These come from Anthropic's infrastructure and are unrelated to your account or request. Common ones are 500 Internal server error and Repeated 529 Overloaded errors (the service is temporarily at capacity). A 529 is not your usage limit and doesn't count against your quota.
What to do: check status.claude.com for incidents and resend in a moment (for a long prompt, just type "try again" instead of pasting it all). If one model is busy, switch with /model to keep working.
② Usage limits
You've reached the usage allowance of your subscription plan. It looks like You've hit your session limit · resets 3:45pm. Unlike server errors, this is specific to your account.
What to do: wait until the reset time shown, or run /usage to see your remaining allowance. On Pro/Max you can buy more with /extra-usage.
③ Authentication (login) errors
Claude Code can't confirm who you are. Examples: Not logged in · Please run /login and Invalid API key.
What to do: run /status to see which credential is active, then /login to sign in again. Note that the ANTHROPIC_API_KEY environment variable takes precedence over /login. So if you logged in with a subscription but are routed through the wrong key, you may need to unset that variable.
④ Network (connection) errors
Claude Code can't reach the API at all, usually due to your own internet, proxy, or firewall. The common one is Unable to connect to API.
What to do: run curl -I https://api.anthropic.com in the same terminal to test reachability (use curl.exe on Windows PowerShell). Behind a corporate proxy, you may need to set HTTPS_PROXY.
⑤ Request errors
The request itself is too large or malformed. The most common is Prompt is too long (the conversation exceeds the limit).
What to do: use /compact (summarize earlier turns to free space) or /clear (start fresh). Run /context to see what's taking up space. For big files, reference them by path instead of pasting, so Claude reads them in chunks.
When an error appears — 3 steps, no panic
- Read the message — read the red text slowly. It usually states the problem in plain English.
- Match the kind — sort which of the five it is (server/usage/login/network/request).
- Take the matching action — retry, wait for reset,
/login,/compact, etc.
Helpers when you're stuck
/status— see which account/credential is currently connected./doctor— check for local configuration problems.- status.claude.com — check for server incidents.
/feedback— if you can't find the cause, report to Anthropic with the transcript (disabled on some providers).
Summary
An error message isn't a scary signal — it's closer to "a note telling you what to check." The keys: (1) most appear only after automatic retries, (2) they split into five kinds — server, usage, login, network, request, and (3) read, classify, then act. For more detailed, symptom-based fixes, continue with install/auth/connection troubleshooting and fixing slow or stuck sessions on this site.
This article summarizes public information from the official Anthropic error reference (code.claude.com/docs/en/errors) for beginners. Error messages and commands can change with product updates, so check your actual screen and the official docs. This site is not an official Anthropic site.