---
title: "Claude Code Error Reference"
aliases: [claude-code-errors, runtime-errors, api-errors]
tags: [claude-code, errors, troubleshooting, api, debugging]
sources: [raw/Error reference.md]
created: 2026-04-17
updated: 2026-04-17
---

# Claude Code Error Reference

Runtime errors Claude Code displays during operation. All three surfaces (CLI, Desktop app, Web) share the same error set since they wrap the same CLI. Errors shown here mean retries (up to 10, exponential backoff) have already been exhausted.

## Retry Behavior

Claude Code retries automatically before surfacing any error. Spinner shows `Retrying in Ns · attempt x/y`.

| Env Var | Default | Effect |
|---|---|---|
| `CLAUDE_CODE_MAX_RETRIES` | 10 | Retry attempts |
| `API_TIMEOUT_MS` | 600000 (10 min) | Per-request timeout in ms |

---

## Server Errors

Originate in Anthropic infrastructure — not your account or request.

### 500 Internal Server Error
- **Cause:** Unexpected API failure, unrelated to your prompt
- **Fix:** Check [status.claude.com](https://status.claude.com), wait a minute, type `try again`. Run `/feedback` if it persists.

### 529 Overloaded
```
API Error: Repeated 529 Overloaded errors
```
- **Cause:** API at capacity across all users; does NOT count against your quota
- **Fix:** Wait a few minutes; run `/model` to switch models (capacity tracked per model)

### Request Timed Out
- **Cause:** High load or very large response; default timeout is 10 min
- **Fix:** Retry; break large tasks into smaller prompts; raise `API_TIMEOUT_MS` for slow networks

### Auto Mode Safety Classifier Unavailable
```
<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool>
```
- **Cause:** Classifier model overloaded; reads/searches/edits in working directory still work
- **Fix:** Retry after a few seconds; transient, no settings change needed

---

## Usage Limits

Tied to your account/plan quota, distinct from server errors.

### Session / Weekly / Model Limit
```
You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
```
- **Fix:** Wait for reset; run `/usage` to check limits; `/extra-usage` to buy more on Pro/Max; monitor with `rate_limits` in [[wiki/claude-code/overview|statusline]] or Desktop usage ring

### 429 Rate Limit
```
API Error: Request rejected (429)
```
- **Cause:** Rate limit on your API key, Bedrock project, or Vertex AI project
- **Fix:** Run `/status` — a stale `ANTHROPIC_API_KEY` may be routing to a low-tier key; lower `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`; reduce parallel subagents

### Credit Balance Too Low
- **Fix:** Add credits at platform.claude.com/settings/billing; enable auto-reload; set per-workspace spend caps

---

## Authentication Errors

Run `/status` to see which credential is active.

| Error | Cause | Fix |
|---|---|---|
| `Not logged in` | No valid credential | `/login` or set `ANTHROPIC_API_KEY` |
| `Invalid API key` | Key rejected | Check Console for revocation; run `env \| grep ANTHROPIC` to find stale `.env` keys |
| `Organization has been disabled` | Disabled org key overrides subscription | Unset `ANTHROPIC_API_KEY`, relaunch |
| `OAuth token revoked/expired` | Session token invalid | `/logout` then `/login` |
| `OAuth scope: user:profile` | Token predates new scope | `/login` to mint fresh token |

**Auth precedence:** `ANTHROPIC_API_KEY` env var overrides `/login` subscription, even in non-interactive mode (`-p`).

---

## Network Errors

Almost always local: VPN, proxy, or firewall — not Anthropic infrastructure.

### Unable to Connect
```
Unable to connect to API (ECONNREFUSED / ECONNRESET / ETIMEDOUT)
```
- **Diagnose:** `curl -I https://api.anthropic.com` from same shell
- **Fix:** Set `HTTPS_PROXY`; set `ANTHROPIC_BASE_URL` for LLM gateways; allow `api.anthropic.com` in firewall
- **WSL:** Check `/etc/resolv.conf` for broken nameserver
- **macOS:** Stale VPN tunnel interfaces (`ifconfig` → remove utun); Docker Desktop can intercept traffic

### SSL Certificate Errors
```
SSL certificate verification failed
Self-signed certificate detected
```
- **Cause:** Corporate proxy doing TLS inspection; Node.js doesn't trust its cert
- **Fix:** `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` — do NOT use `NODE_TLS_REJECT_UNAUTHORIZED=0`

---

## Request Errors

API received the request but rejected its content.

### Context Window Full
```
Prompt is too long
```
- **Fix:** `/compact` to summarize; `/clear` to start fresh; `/context` to inspect usage; disable unused MCP servers with `/mcp disable <name>`; trim `CLAUDE.md` files
- **Note:** Auto-compact is on by default; re-enable if `DISABLE_AUTO_COMPACT` was set
- **Subagents:** Inherit all parent MCP tool definitions — disable unused MCP before spawning

### Compaction Failed
```
Error during compaction: Conversation too long
```
- **Fix:** Press Esc twice → step back several turns → run `/compact` again; or `/clear` + `/resume`

### Request Too Large (30 MB HTTP limit)
- **Fix:** Press Esc twice; reference large files by path instead of pasting

### Image Too Large
- **Fix:** Press Esc twice; max 8000px longest edge (single image), 2000px when many images in context; take tighter screenshots

### PDF Errors
- Too large (>100 pages / 32 MB): use Read tool with page range or `pdftotext`
- Password protected: remove protection first
- Invalid: re-export from source

### Extra Inputs Not Permitted (400)
```
API Error: 400 ... Extra inputs are not permitted ... context_management
```
- **Cause:** LLM gateway strips `anthropic-beta` header but forwards body with beta-only fields
- **Fix:** Configure gateway to forward `anthropic-beta`; or set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`

### Model Not Found / No Access
- **Fix:** Run `/model` to pick from available models; use aliases (`sonnet`, `opus`) instead of versioned IDs to avoid staleness

### Opus Not Available on Pro Plan
- **Fix:** `/model` to select an included model; if recently upgraded, `/logout` then `/login` to refresh token

### `thinking.type.enabled` Not Supported
- **Cause:** Claude Code version < v2.1.111 on Opus 4.7
- **Fix:** `claude update` to v2.1.111+; or switch to Opus 4.6 / Sonnet

### Thinking Budget Exceeds Output Limit
```
max_tokens must be greater than thinking.budget_tokens
```
- **Cause:** Common on Bedrock/Vertex when `MAX_THINKING_TOKENS` > provider output limit
- **Fix:** Lower `MAX_THINKING_TOKENS` or raise `CLAUDE_CODE_MAX_OUTPUT_TOKENS`

### Tool Use / Thinking Block Mismatch (400)
```
API Error: 400 due to tool use concurrency issues
```
- **Cause:** Conversation history corrupted (interrupted tool call or mid-stream edit)
- **Fix:** `/rewind` or Esc × 2 to step back to a clean checkpoint

---

## Response Quality Seems Off (No Error)

Claude Code never silently downgrades models. Check:

1. **`/model`** — confirm expected model; `ANTHROPIC_MODEL` env var may override
2. **`/effort`** — check reasoning level; raise for hard tasks (`ultrathink`)
3. **`/context`** — check window fill level; `/compact` or `/clear` if near capacity
4. **`/doctor`** — flags oversized `CLAUDE.md` files and subagent definitions
5. **Rewind, don't correct** — press Esc × 2 or `/rewind` before the bad turn; replying keeps the wrong answer in context

---

## Reporting

- `/feedback` — sends transcript + description to Anthropic (unavailable on Bedrock/Vertex/Foundry)
- `/doctor` — local config check
- [status.claude.com](https://status.claude.com) — active incidents
- GitHub issues: anthropics/claude-code

---

## Key Takeaways

- **Retries are automatic** — when you see an error, 10 retries with backoff have already run
- **529 ≠ your quota** — overloaded errors don't count against usage limits
- **`ANTHROPIC_API_KEY` wins** — an env var key always overrides `/login` subscription, including disabled-org keys hiding in `.env` files
- **Gateway proxy issues** surface as `Extra inputs not permitted` when `anthropic-beta` header is stripped
- **Context errors:** `/compact` → Esc×2 to step back → `/compact` again → `/clear` as last resort
- **Image errors persist** until you Esc×2 past the turn that added the image
- **Quality issues:** check `/model`, `/effort`, `/context` before assuming model regression; prefer `/rewind` over in-thread correction

## Related

- [[wiki/claude-code/overview|Claude Code Overview]] — full product capabilities, all surfaces
- [[wiki/claude-code/mcp-integration|MCP Integration]] — MCP server errors and `/mcp disable` usage
- [[wiki/claude-code/custom-subagents|Custom Subagents]] — context inheritance issues when spawning subagents

---

## Sources

- `raw/Error reference.md` — scraped from code.claude.com/docs/en/errors
