ES · Leer en español Explore for free

Recipe · Basic · 5 min

Claude Code errors: 529, 401, 403, limits and how to fix them

The exact message, the cause and the fix for the most common Claude Code errors: 529 Overloaded, 401, 403, usage limits, full context, PATH and MCP.

Tested with Claude Code 2.1.316 · reviewed

The problem

You're in the middle of a task and Claude Code stops with a message: API Error: Repeated 529 Overloaded errors, Not logged in · Please run /login, Context limit reached... Each one has a different cause and a different fix, and retrying blindly doesn't always help. This page collects the most frequent errors with the literal message (so you can find it with Ctrl+F), what causes it and what to do, step by step.

Messages marked Reproduced with 2.1.316 were triggered on Linux with a temporary home folder (without touching the real configuration). The rest were copied verbatim from the official error reference and the installation and login guide.

The solution

1. First: check which credential and state you have

Three commands solve half the cases because they tell you where the failure is:

# From your terminal, if claude doesn't even start properly
claude doctor

And inside a session:

/status    # which account, organization and credential are active
/doctor    # checks installation, settings, extensions and context usage
/mcp       # status of each MCP server

If the error comes from the server (500, 529), also check status.claude.com before changing anything on your machine.

2. API Error: Repeated 529 Overloaded errors

Exact message (official documentation):

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

Cause: the API is temporarily at capacity across all users. Claude Code has already retried several times before showing the message. It is not your usage limit and doesn't count against your quota.

Fix:

  1. Check status.claude.com for capacity notices.
  2. Wait a few minutes and try again. Your message is still in the conversation, so you can just type try again.
  3. If you're in a hurry, switch models with /model: capacity is tracked per model. Claude Code sometimes suggests this itself with a notice such as Opus is experiencing high load, please use /model to switch to Sonnet.

Its close cousin is API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. A 5xx from the API is an internal failure of the service, not of your prompt or account: same fix (status, wait, retry). If it persists with no posted incident, use /feedback.

3. Usage limit reached: You've hit your session limit

Exact messages (official documentation):

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm
You've hit your Sonnet limit · resets 3:45pm

Cause: subscription plans include a rolling allowance. The session, weekly or model-family allowance ran out.

Fix:

  1. Run /usage to see your limits and when they reset.
  2. If the notice is about Opus or Sonnet, switch with /model to a model from another family and keep working. If it's the session or weekly limit, switching models doesn't help: those limits are shared across all models.
  3. Wait for the time shown in the message. In an interactive session signed in with a claude.ai subscription, Claude Code can wait and continue the task on its own after the reset (the Continue automatically at usage limit option in /config).
  4. If you need more, /usage-credits buys additional usage on Pro, Max and Ultra, or requests it from your admin on Team and Enterprise.

Two similar errors that are not your plan quota:

4. 401 and login errors

Reproduced with 2.1.316 (with no credential at all):

$ claude -p "hello"
Not logged in · Please run /login

Reproduced with 2.1.316 (with a made-up key in ANTHROPIC_API_KEY):

$ ANTHROPIC_API_KEY=sk-ant-api03-claveinventada claude -p "hello"
Invalid API key · Fix external API key

Other messages in the same family (official documentation):

OAuth token revoked · Please run /login
Please run /login · API Error: 401 OAuth token has expired ...
Please run /login · API Error: 401 Invalid authentication credentials
Login expired · Please run /login

Cause: Claude Code can't prove who you are. Either there's no credential, the key is wrong or revoked, or your claude.ai login expired and couldn't be renewed. 401 Invalid authentication credentials means the API recognized the credential but rejected the account or organization behind it (revoked, deactivated or without access).

Fix:

  1. Run /status to see which credential is active.
  2. If you use your subscription, run /login. If it keeps failing, do a clean reset: /logout, close Claude Code, start it with claude and sign in again.
  3. If you see Invalid API key, look for stray keys in your environment. direnv, .env shell plugins and editor terminals can load an old key without you noticing:
env | grep ANTHROPIC
  1. If you don't want to use that key, unset it and sign in with your subscription. An approved ANTHROPIC_API_KEY takes precedence over your login, so /login alone doesn't replace it:
unset ANTHROPIC_API_KEY
claude
  1. If you're asked to log in again and again, check that your system clock is accurate: token validation depends on it.
  2. In automation (CI, -p) where you can't sign in interactively, use ANTHROPIC_API_KEY or generate a long-lived token with claude setup-token.

5. API Error: 403 Request not allowed

Exact message (official documentation): API Error: 403 Request not allowed, right after logging in.

Cause: the account signed in but isn't allowed to use Claude Code, or a corporate proxy is interfering.

Fix:

  1. Pro, Max or Ultra: confirm your subscription is active at claude.ai/settings.
  2. Console account: your user needs the "Claude Code" or "Developer" role. An admin assigns it at platform.claude.com/settings/members.
  3. Behind a proxy: review the network configuration.

If the 403 shows up while installing (curl: (22) The requested URL returned error: 403), it's usually a proxy or network filter blocking the download, or Claude Code isn't available in your country.

6. Full context: Context limit reached and compaction errors

Exact messages (official documentation):

Context limit reached · /compact or /clear to continue
Prompt is too long
Prompt is too long · automatic compaction failed: <the underlying error>
Autocompact is thrashing: the context refilled to the limit...

Cause: the conversation plus attached files exceed the model's context window. Auto-compaction normally prevents this; when it's off or fails, you get this error.

Fix:

  1. Run /compact to summarize earlier turns and free space, or /clear to start fresh.
  2. Run /context to see what fills the window: system prompt, tools, memory files and messages.
  3. Disable the MCP servers you aren't using, because their tool definitions take context on every request:
/mcp disable <name>
  1. Trim large CLAUDE.md files or move instructions into path-scoped rules that only load when relevant.
  2. If /compact answers Not enough messages to compact., the conversation is a single exchange and there's nothing to summarize: run /clear and resend with less pasted text or smaller files.
  3. If you see automatic compaction failed: ..., fix the error named after the colon first (for example, an authentication error); /compact fails the same way until you do.
  4. If you see Autocompact is thrashing, a file or tool output refills the context right after compacting. Ask Claude to read that file in chunks (a line range or a function), compact with a focus (/compact keep only the plan and the diff) or move that work to a subagent.
  5. If you turned auto-compact off in /config, turn it back on.

7. claude: command not found after installing

Reproduced with 2.1.316 (with a PATH without ~/.local/bin):

bash: claude: command not found

The message varies by platform (official documentation):

PlatformMessage
macOSzsh: command not found: claude
Linuxbash: claude: command not found
Windows CMD'claude' is not recognized as an internal or external command
PowerShellclaude : The term 'claude' is not recognized as the name of a cmdlet

Cause: the install finished, but the folder holding the program (~/.local/bin on macOS and Linux, %USERPROFILE%\.local\bin on Windows) isn't in your PATH. The installer reports it under Setup notes: but doesn't change PATH for you.

Fix on Linux and macOS:

  1. Check the program exists:
ls -la ~/.local/bin/claude
  1. Check whether the folder is in your PATH (no output means it isn't):
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
  1. Add it. For Bash on Linux:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

For Zsh (the macOS default), replace ~/.bashrc with ~/.zshrc. For Bash on macOS, use ~/.bash_profile.

  1. Verify:
claude --version

Fix on Windows (PowerShell):

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

Close and reopen the terminal. If you use an editor's terminal (VS Code, Cursor), quit and reopen the whole editor: it inherits the editor's PATH. Note: the VS Code extension bundles its own copy of Claude Code and doesn't put claude on your PATH; to use it from a terminal you need the standalone install.

8. Permissions and sandbox: denied or blocked commands

In claude -p and the Agent SDK. Since version 2.1.302, a -p run with no permission mode starts in Manual mode (default): anything that needs approval is denied, because nobody is there to answer. Fix, pick one:

# Allow only what it needs
claude -p "Run the test suite and fix any failures" --allowedTools "Bash(npm test)"

# Or let the auto mode classifier review each action
claude -p "Run the test suite and fix any failures" --permission-mode auto

With the sandbox on Linux or WSL2. The sandbox needs bubblewrap and socat. If one is missing, the Dependencies tab in /sandbox says so. On Ubuntu or Debian:

sudo apt-get install bubblewrap socat

Restart Claude Code after installing them: the check runs at startup. On Ubuntu 24.04 and later, if sysctl kernel.apparmor_restrict_unprivileged_userns returns 1, AppArmor stops bubblewrap from working; the sandbox guide has the exact profile to add.

If you required the sandbox (sandbox.failIfUnavailable) and it couldn't start, each command is refused with Sandbox is required but failed to initialize: <reason>. Fix what the reason names and restart.

Other known failures inside the sandbox: docker is incompatible (take it out with an excludedCommands pattern such as docker compose *) and jest hangs because of watchman (use jest --no-watchman).

9. An MCP server won't connect

Reproduced with 2.1.316 (a stdio server whose command doesn't exist and an HTTP server on a closed port):

$ claude mcp list
Checking MCP server health…

fantasma: /ruta/que/no/existe/servidor  - ✘ Failed to connect — ENOENT: no such file or directory, posix_spawn '/ruta/que/no/existe/servidor'
remoto: http://127.0.0.1:9/mcp (HTTP) - ✘ Failed to connect — ECONNREFUSED: Unable to connect. Is the computer able to access the url?

Reproduced with 2.1.316 (a server that starts and exits right away):

$ claude mcp get sale
sale:
  Scope: Local config (private to you in this project)
  Status: ✘ Failed to connect
  Issue: CONNECTION_CLOSED: Connection closed

Reproduced with 2.1.316 (from another folder, or with a malformed .mcp.json):

No MCP servers configured. Use `claude mcp add` to add a server.

[Failed to parse] Project config (shared via .mcp.json)
 └ [Error] MCP config is not a valid JSON

Cause and fix by message:

  1. ENOENT: the server command doesn't exist at that path or isn't installed. Run the same command yourself in the terminal (for example npx -y @playwright/mcp@latest) to see the real error. If it works there but not in Claude Code, check with claude mcp get <name> that the saved command matches; the usual culprit is a missing -- before the command in claude mcp add.
  2. ECONNREFUSED or no response: the URL is wrong or the server isn't running. Test it with curl -I <url>. A 404 or 405 means the server answers; a 401 or 403 means you need to authenticate.
  3. CONNECTION_CLOSED: the process started and exited. It's almost always missing an environment variable (an API key). Pass it with --env KEY=value on claude mcp add.
  4. No MCP servers configured: local-scoped servers are tied to the project where you added them. Add it again in this project or use --scope user. Claude Code only reads ~/.claude.json and <project>/.mcp.json, not paths such as ~/.claude/mcp.json.
  5. MCP config is not a valid JSON: fix the .mcp.json syntax. Claude Code reads it at session start, so restart the session after editing it.
  6. Timeout at startup: the first npx run can take longer than the 30-second default. Raise the limit:
MCP_TIMEOUT=60000 claude

To remove a broken server: claude mcp remove <name> -s local.

Check it

After each fix, confirm from the terminal:

claude --version
claude mcp list

Expected output: the version (for example 2.1.316 (Claude Code)) and each MCP server with ✔ Connected. Inside a session, /status should show the account or key you expect, and /context should leave free room in the window.

Why it works

Almost all of these errors come from three different places, and the fix depends on which: the service (500, 529, temporary throttling; fixed by waiting or switching models), your account or credential (401, 403, usage limits; fixed with /status, /login and checking ANTHROPIC_API_KEY) or your machine (PATH, sandbox, MCP, context; fixed with local configuration). Identifying the source first saves you from reinstalling when the API is just overloaded, or waiting when there's actually an old key in your environment. The full, up-to-date list of messages is in the error reference, and installation errors are in Troubleshoot installation and login.

Common mistakes

FAQ

Does a 529 error use up my usage limit?

No. According to the official documentation, a 529 means the API is at capacity for everyone and it doesn't count against your quota.

How do I know if Claude Code is down for everyone?

Check status.claude.com. If error messages end with a different status URL, that's your provider's (Bedrock, Google Cloud, Microsoft Foundry or your gateway).

Do I lose the conversation if I close Claude Code because of an error?

No. Run claude --resume in the same folder to pick the session back up.

What do I do with an error that isn't listed here?

Search for the exact text in the official error reference, which has a table of messages, and run /doctor. If it persists with no posted incident, send /feedback so Anthropic can investigate with your request details.

All recipes