# Claude Code Error reference

> Claude Code: Runtime errors, HTTP/API statuses, retries, usage limits, authentication, networking, request failures, and CLI conflicts.

URL: https://docs.passion8.cc/en/docs/claude-code/error-reference
Language: en
Publisher: Passion8

This page diagnoses failures after Claude Code starts. For installation, PATH, login, and OAuth, see [Installation troubleshooting](https://docs.passion8.cc/en/docs/claude-code/install-troubleshooting). For unloaded settings, hooks, MCP, and memory, see [Configuration debugging](https://docs.passion8.cc/en/docs/claude-code/configuration-debugging).




A Passion8 error may originate upstream, at the gateway, on your network, or in local configuration. Identify the category before retrying, changing models/settings, or contacting support.




## Quick diagnosis

| Error | Category | First action |
| --- | --- | --- |
| API Error: 500 | Server failure | Retry later; check provider/gateway status |
| Repeated 529 Overloaded errors | Capacity | Wait or select another available model |
| Request timed out | Server or network | Split the task; adjust API_TIMEOUT_MS if appropriate |
| Server error mid-response | Interrupted stream | Inspect partial output, then continue |
| You've hit your session limit | Subscription/session limit | Wait for reset or use an available provider |
| Usage credits required for 1M context | Context eligibility | Disable 1M or meet official account requirements |
| Request rejected (429) | Rate limit | Wait, reduce concurrency/background agents |
| Credit balance is too low | Balance | Check Passion8 balance/key |
| Not logged in | Authentication | Official login or correct Passion8 variables |
| Invalid API key | Authentication | Check credential and variable |
| Unable to connect to API | Network | Proxy, DNS, firewall, Base URL |
| SSL certificate | TLS | Configure corporate CA or fix proxy certificate |
| Prompt is too long | Context size | Compact, remove large content, split tasks |
| Request too large | Payload size | Reduce attachments, images, PDFs, or tool output |
| selected model | Model availability | Select an available Passion8 model |
| thinking budget exceeds output limit | Thinking configuration | Lower thinking budget or increase output limit |
| --bg and --print conflict | CLI flags | Choose background or print, not both |

## Automatic retries

Claude Code retries temporary failures, including 5xx, 529, some 429s, timeouts, and disconnects. A final error often means retries were exhausted.

| Variable | Purpose | Recommendation |
| --- | --- | --- |
| CLAUDE_CODE_MAX_RETRIES | Retry count | Lower for fast-failing CI |
| CLAUDE_CODE_RETRY_WATCHDOG | Extended capacity retries unattended | Use deliberately for overnight jobs |
| API_TIMEOUT_MS | Per-request timeout | Increase for slow proxies or long output when appropriate |

Certificate failures and errors after visible output are not blindly replayed. Preserving partial output avoids duplicate tool execution.

## Server errors

### 500

A provider/gateway internal failure is not a malformed prompt or permission-rule problem.

1. Wait one or two minutes and retry.
2. Select another available model with /model.
3. If isolated to Passion8, check its console and model supply status.
4. If isolated to the official API, check Anthropic status.

### 529

Capacity congestion is not the same as exhausted account credit. Avoid many background agents hitting one model simultaneously.

| Scenario | Recommendation |
| --- | --- |
| Interactive development | Retry later or use another available Sonnet/Opus model |
| Print-mode script | Bound retries and preserve input on failure |
| Batch/multiple agents | Reduce concurrency and queue work |
| One-hour-cache workload | Retry without unnecessary model/effort changes |

### Interrupted response

When partial output already exists, replaying the whole turn can repeat tool calls.

- Read the partial answer.
- Ask to continue from the last section.
- If a tool ran before interruption, inspect actual file/command state first.

## Usage and credit

| Error | Meaning | Passion8 action |
| --- | --- | --- |
| Session/weekly limit | Official subscription limit | A gateway key does not alter subscription limits; gateway variables select the API route |
| 1M context credits required | Official eligibility missing | Use normal context and compact instead of forcing 1M |
| Temporary limiting requests | Provider throttling | Reduce concurrency and wait |
| 429 | Request or quota window limit | Reduce concurrent large-context requests |
| Credit balance too low | Key/account balance | Check balance, key state, and model permissions |

## Authentication errors

| Path | Variables/commands | Use |
| --- | --- | --- |
| Official account | /login, OAuth, subscription | Official hosted surfaces and remote features |
| API/gateway | ANTHROPIC_BASE_URL, AUTH_TOKEN, API_KEY | Passion8, custom providers, CI |

Recommended Passion8 configuration:

```bash
export ANTHROPIC_BASE_URL="https://passion8.cc"
export ANTHROPIC_AUTH_TOKEN="sk-YOUR_PASSION8_API_KEY"
claude -p "Reply only with ok"
```




Claude Code uses the root https://passion8.cc without /v1. The /v1 suffix is common in OpenAI-compatible clients, not this setup.




| Error | Check |
| --- | --- |
| Not logged in | For Passion8, ensure gateway variables reached the process; official subscription uses /login |
| Could not resolve authentication method | Avoid incomplete/conflicting OAuth, API-key, and gateway configuration |
| Invalid API key | Complete active key in the correct variable |
| Organization disabled | Official organization/policy; local settings cannot repair it |
| OAuth token expired | Reauthenticate the official account or use the intended gateway credentials |
| Cloud-provider credentials | Provider credential chain and profile |

## Network and certificates

| Symptom | Cause | Action |
| --- | --- | --- |
| Unable to connect | DNS/proxy/firewall/URL | Check curl -I https://passion8.cc and proxy settings |
| TLS certificate | Corporate interception or missing CA | NODE_EXTRA_CA_CERTS or IT-managed trust |
| Cloud session host not allowed | Disallowed host | Use local execution or update the allowlist |
| Long wait before failure | Proxy handshake or packet loss | Investigate network; adjust timeout only as needed |

## Request errors

### Context too long

Prompt-too-long, request-too-large, and compaction failures often involve excessive context or attachments.

- Inspect /context.
- Summarize with /compact.
- Start a new session with /clear.
- Remove unnecessary logs, screenshots, PDFs, and MCP output.
- Split large repository work by directory.

### Models and thinking

| Error | Action |
| --- | --- |
| Selected model issue | Choose one actually available from the provider |
| Opus unavailable | Use Sonnet or an account/provider with Opus access |
| Organization restriction | Ask the administrator to change policy |
| Thinking unsupported | Use a compatible model or supported non-thinking configuration |
| Thinking budget exceeds output | Reduce MAX_THINKING_TOKENS or raise output budget on compatible models |
| Tool-use block mismatch | Inspect request structure and gateway body rewriting |

## Cache effects

Errors do not themselves change TTL, but recovery actions can alter cache identity.

| Action | Effect |
| --- | --- |
| Retry same model/effort | More likely to reuse the prefix |
| Switch model | Different cache identity; initial miss likely |
| Change effort/thinking | Can invalidate reuse |
| Continue after compact | Summary replaces history |
| Repair MCP/hooks | Schemas or instructions may change |
| Use clean configuration | Diagnostic only, not a normal hit-rate measurement |

See [Commands and cache effects](https://docs.passion8.cc/en/docs/claude-code/command-cache) and [Prompt caching](https://docs.passion8.cc/en/docs/claude-code/prompt-caching).

## Official references

- [Error reference](https://code.claude.com/en/docs/en/errors.md)
- [Troubleshoot installation and login](https://code.claude.com/en/docs/en/troubleshoot-install.md)
- [Troubleshooting](https://code.claude.com/en/docs/en/troubleshooting.md)
- [Prompt caching](https://code.claude.com/en/docs/en/prompt-caching.md)