Claude Code CLI Errors: How to Fix the Common Ones

Claude Code CLI Errors: The Fixes I Actually Use

It's 11 p.m., you finally have an hour to ship a feature, you open a terminal, type your prompt into Claude Code — and instead of a diff, you get a red authentication_error. Or worse, a wall of 429s right as you hit your stride. I've been there more times than I'd like to admit. The good news: almost every Claude Code CLI error falls into one of about six buckets, and each has a boring, reliable fix.

This is the field guide I wish I'd had. No hand-waving, just the commands and the reasoning behind them.

Most "Claude Code is broken" moments aren't bugs in the tool. They're auth state, billing state, or a transient overload on the API. Knowing which one you're staring at is 90% of the fix.

First: Read the Error, Not Your Panic

Claude Code sits on top of the Anthropic API, so the errors you see usually map to a standard HTTP status code. Before you reinstall anything, identify the category. Here's the authoritative mapping from Anthropic's official error reference — memorize the shape of it:

HTTP status	Error type	What it really means
400	invalid_request_error	Malformed request — bad params or body
401	authentication_error	Your API key / login is missing or invalid
403	permission_error	No access to the resource — or a billing problem (billing_error also surfaces as 403, distinguished by the .type field)
404	not_found_error	Resource doesn't exist (wrong model id, wrong endpoint)
413	request_too_large	Payload exceeds the size limit
429	rate_limit_error	You're sending too fast / hit a quota
500	api_error	Something broke on Anthropic's side
529	overloaded_error	The API is temporarily overloaded

A few things I want to nail down because they trip people up constantly:

• There is no HTTP 402 here. If your card fails or you run out of credit, you do not get a 402 billing_error. Billing failures come back as 403 — you tell them apart from a true permission issue by reading the .type field in the response, not the status code.
• request_too_large is 413, not 400. When you dump a giant file or a huge context into a single call and it bounces, look for 413, not a generic bad-request.

Get the category right and the fix is almost mechanical.

Problem 1: authentication_error (401) on Every Command

This is the most common one, and it's almost always stale or absent credentials.

Cause: Claude Code can't find a valid session token or API key. Maybe you never logged in on this machine, your session expired, or you set a malformed ANTHROPIC_API_KEY in your shell that's overriding your interactive login.

The fix — prefer the in-session login. The cleanest path is to authenticate from inside Claude Code itself:

# inside a Claude Code session, just type:
/login

This launches the browser-based OAuth flow and stores the session for you. I reach for /login first because it avoids the whole "is my env var stale?" rabbit hole.

If you are deliberately using an API key (CI, headless server), check that the variable is actually set and not empty:

# does the key exist in this shell? (don't print the whole thing)
echo "${ANTHROPIC_API_KEY:+key is set}"

A frequent gotcha: an empty or quoted-wrong ANTHROPIC_API_KEY in your .zshrc silently shadows your good login. Unset it and re-run /login:

unset ANTHROPIC_API_KEY

Version note: auth flags and subcommands change between releases. Before you trust a flag you read on some forum, run claude --help and check the official Claude Code docs. I deliberately avoid memorizing CLI flags that may have moved.

Problem 2: permission_error / Billing Issues (403)

You're logged in, but commands fail with a 403. Two very different things wear this same status code.

1. A real permission problem — the model or feature isn't enabled for your account/org.
2. A billing problem — billing_error also returns 403. Out of credit, expired card, or a spending cap hit.

How to tell them apart: look at the .type field in the error body. If it says billing_error, head to your Anthropic Console billing page and check your balance and payment method. If it's permission_error, verify you're using a model your plan can access and that your org admin has granted it.

I once burned 20 minutes "fixing auth" — re-logging in, regenerating keys — when the actual issue was a lapsed card. The 403 was screaming billing_error the whole time and I wasn't reading the body.

Problem 3: rate_limit_error (429)

You're moving fast, kicking off parallel tasks, and suddenly everything returns 429.

Cause: You've exceeded requests-per-minute or a token quota for your tier. Heavy multi-file edits or rapid retries pile up fast.

Fixes:

• Back off and retry with jitter. A 429 usually includes a retry-after hint. Honor it instead of hammering.
• Batch your work. Instead of ten tiny prompts, give Claude Code one well-scoped task. Fewer, larger calls beat a flurry of small ones.
• Check your tier. Higher usage tiers get higher limits; if you're consistently capped, that's a billing-side upgrade, not a code fix.

# crude backoff if you're scripting around the API
for i in 1 2 4 8; do
  run_claude_task && break
  echo "rate limited; sleeping ${i}s" && sleep "$i"
done

Problem 4: overloaded_error (529)

This one is not your fault. A 529 means Anthropic's API is temporarily overloaded — usually during peak hours or a traffic spike.

Fix: wait and retry with exponential backoff. There's nothing to "fix" locally. Don't regenerate keys, don't reinstall — you'll just waste your evening. I've written up the full backoff strategy and what 529 really signals in a dedicated guide: see the Claude API 529 overloaded error guide.

Rule of thumb: 401/403 = you (auth or billing). 429 = your pace. 500/529 = them. Treat each accordingly and you stop thrashing.

Problem 5: Install & Node Errors

Plenty of "Claude Code won't start" reports are really npm/Node problems, and the same hygiene applies across the whole CLI-agent ecosystem (Claude Code, OpenAI's Codex CLI, and others).

Cause: wrong Node version, or a global install that needed sudo and left broken permissions.

Fixes:

• Use Node 18+. Older runtimes throw cryptic syntax/engine errors. Confirm with node -v.
• Don't sudo npm install -g. A sudo global install creates root-owned files that bite you later. Use a version manager like nvm so global installs live in your user space.

# install/manage Node cleanly with nvm, then global-install without sudo
nvm install 20
nvm use 20
node -v   # expect v18+ ; v20 is a safe bet

If you also run OpenAI's Codex CLI alongside Claude Code, the same rules hold — the package is @openai/codex, it needs Node 18+, and you should avoid sudo global installs there too. For Codex auth specifically, device login is codex login --device-auth (note: --device-auth, not --device-code), and if you authenticate with an API key, pipe it via stdin rather than passing it as an argument so it never lands in your shell history:

# correct: key never appears as a CLI argument
printenv OPENAI_API_KEY | codex login --with-api-key

That stdin-piping habit is worth carrying everywhere: secrets passed as CLI args leak into ps, shell history, and logs.

Problem 6: request_too_large (413) and not_found_error (404)

Two quick ones that look scarier than they are:

• 413 request_too_large: you fed too much into one call — a massive file, an enormous pasted log. Split the work, point Claude Code at specific files instead of the whole tree, or summarize before sending. Remember this is 413, not 400.
• 404 not_found_error: usually a wrong/retired model id or a typo'd endpoint. Verify the exact model name against the current docs; model ids get deprecated.

Do's and Don'ts

Do	Don't
Read the HTTP status and the .type field before acting	Assume every red error is "broken auth"
Use in-session /login for Claude Code auth	Invent CLI flags you half-remember — check --help
Pipe API keys via stdin (printenv KEY | ... --with-api-key)	Pass secrets as CLI arguments (they leak to history/logs)
Back off and retry on 429/529	Hammer retries during a 529 overload
Manage Node with nvm, use Node 18+	sudo npm install -g (root-owned, permission hell)
Treat billing_error (403) as a billing fix	Hunt for a "402" — there is no HTTP 402 here

A Quick Triage Checklist

When something fails, I run this in my head in order:

1. What's the HTTP status? That picks the category instantly.
2. 401? Run /login. Check for a shadowing ANTHROPIC_API_KEY.
3. 403? Read .type. billing_error → console billing. permission_error → model/plan access.
4. 429? Slow down, batch, honor retry-after.
5. 413? Send less. Target specific files.
6. 500/529? Not you. Backoff and retry; check status.
7. Won't even launch? Node version + non-sudo reinstall.

If you want to go deeper on writing prompts that don't waste calls (which indirectly keeps you under rate limits), our prompt analyzer and the broader tips on the blog are a good next stop.

Wrapping Up

Here's the honest takeaway from someone who's debugged this stuff at midnight more than once: Claude Code rarely "breaks." It reports state. Authentication state, billing state, your request pace, or the API's current load. Once you stop treating every red line as a mysterious bug and start reading the status code plus the .type field, the fixes become a short, repeatable checklist — /login, check billing, back off, send less, fix Node.

Keep the error table above handy, remember that there's no 402 and 413 means too-large, and you'll spend a lot less time thrashing and a lot more time shipping. Pin this page, and the next time a 429 or authentication_error greets you at 11 p.m., you'll know exactly which lever to pull.

Next action: bookmark Anthropic's error-codes reference, skim the 529 overload guide, and run claude --help once tonight so the current flags are fresh in your head before you need them.