# Error Code Reference

This document provides detailed information about various error codes you may encounter while using Claude Code and their solutions.

## Error Code Quick Reference

| Code | Type | Description | Severity |
|------|------|-------------|----------|
| 400 | Client Error | Malformed request | Low |
| 401 | Auth Error | Invalid API Key | Medium |
| 402 | Channel Error | Upstream channel temporarily refusing | Medium |
| 403 | Permission Error | Access denied | Medium |
| 429 | Rate Limit | Too many requests | Medium |
| 500 | Server Error | Internal error | High |
| 502 | Gateway Error | Upstream unavailable | High |
| 503 | Service Unavailable | Temporarily overloaded | High |
| 529 | API Overloaded | Claude API overloaded | High |

---

## 429 - Too Many Requests

One of the most common errors, indicating too many requests in a short period.

### Error Message

```text
Error: 429 Too Many Requests
Rate limit exceeded. Please slow down your requests.
```

### Common Causes

1. **Too frequent requests**: Sending multiple requests in rapid succession

2. **Too many concurrent requests**: Running multiple Claude Code instances simultaneously

3. **Token limit reached**: Consuming too many tokens in a short time

4. **Quota exhausted**: Daily/monthly quota depleted

### Solutions

**Immediate Actions**:
```bash
# Wait 30-60 seconds before retrying
sleep 60 && claude "your question"
```

**Long-term Solutions**:

1. Reduce request frequency, avoid rapid consecutive sends

2. Use `/compact` command to compress context

3. Split large tasks into smaller batches

4. Consider upgrading to a higher quota plan

> **QCode.cc Advantage**: Professional load balancing with multi-account pools to distribute request pressure, effectively reducing 429 errors.

---

## 502 - Bad Gateway

Indicates the gateway or proxy server received an invalid response from upstream.

### Error Message

```text
Error: 502 Bad Gateway
The server received an invalid response from the upstream server.
```

### Common Causes

1. **Upstream temporarily unavailable**: Anthropic API server issues

2. **Network connection interrupted**: Connection dropped during request

3. **Proxy server issues**: Intermediate node failure

4. **Request timeout**: Response time exceeded gateway limit

### Solutions

**Immediate Actions**:
```bash
# Check network connection
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models

# Wait and retry
sleep 30 && claude "your question"
```

**Long-term Solutions**:

1. Check local network stability

2. Try switching network environments

3. Use VPN or more stable network

4. Contact support if persistent

> **QCode.cc Advantage**: Multi-region deployment, CDN acceleration, automatic failover, ensuring 99.9% availability.

---

## 401 - Unauthorized

Invalid API Key or missing valid authentication.

### Error Message

```text
Error: 401 Unauthorized
Invalid API key or authentication token.
```

### Common Causes

1. **Incorrect API Key**: Missing characters or extra spaces when copying

2. **Expired API Key**: Subscription has expired

3. **Disabled API Key**: Banned due to policy violation

4. **Environment variable not set**: `ANTHROPIC_AUTH_TOKEN` not configured

### Solutions

**Verify API Key**:
```bash
# Check environment variable
echo $ANTHROPIC_AUTH_TOKEN

# Confirm correct format (starts with cr_)
# Correct example: cr_xxxxxxxxxxxxxxxxxxxx
```

**Steps**:

1. Login to [QCode.cc Dashboard](https://qcode.cc/dashboard) to check API Key status

2. Confirm subscription is active

3. If banned, contact support (QCode.cc provides immediate replacement service)

---

## 402 - Payment Required

The upstream channel refused this request. **This is usually not a problem with your key or your configuration** — requests from the same key to other models at the same time normally succeed.

### What you see

```text
Error: 402 Payment Required
```

In Claude Code it usually looks like the request simply failing with no response content; from a script or SDK you get HTTP 402.

### Common causes

1. **The upstream channel is temporarily unavailable**: the QCode gateway never generates a 402 itself — it relays the status returned by the upstream

2. **Concentrated on one model**: at any given moment one model may see a high 402 rate while the others are completely fine

3. **Depends on the endpoint domain**: different domains route through different upstream paths, and the chance of hitting a 402 can differ substantially

4. **Not related to your balance**: running out of account balance or plan quota does not return 402 — that case says "daily cost limit reached", see the [FAQ](/docs/reference/faq)

### What to do

**1. Switch model (most effective)**

```bash
# Switch inside a session
/model sonnet

# Or specify at launch
claude --model claude-sonnet-5
```

**2. Switch endpoint domain**

```bash
# Mainland China
export ANTHROPIC_BASE_URL=https://asia.qcode.cc/api

# Global (Route 53 picks the nearest node)
export ANTHROPIC_BASE_URL=https://api.qcode.cc/api
```

All four domains take the same key, so switching needs no other configuration change. See [Endpoints & API Formats](/docs/getting-started/endpoints-and-api-paths).

**3. Don't write a tight retry loop**

A 402 does not go away by resending immediately; hammering only makes it worse. Use exponential backoff, or just switch model — see "Error handling best practices" on this page.

**4. If it persists, contact support**

Include the time it happened, the model id and the endpoint domain, and reach us through [live chat](javascript:void(Tawk_API.toggle())) or [hi@qcode.cc](mailto:hi@qcode.cc).


### `INSUFFICIENT_BALANCE` / `Insufficient account balance`

Some 402/403 responses carry JSON like `"code":"INSUFFICIENT_BALANCE", "message":"Insufficient account balance"`. **This does not mean your QCode balance ran out.** It is a temporary condition on one upstream channel passed through verbatim — unrelated to your account. When your own quota is used up, the message you actually see is "Daily cost limit reached" (see [FAQ](/docs/reference/faq)).

What to do: wait and retry / switch model / switch access domain (steps ①–③ above all apply); if it persists, contact support with the request id. Full checklist: [troubleshooting guide](/docs/reference/troubleshooting).

---

## 403 - Forbidden

Request rejected by server, usually due to insufficient permissions.

### Error Message

```text
Error: 403 Forbidden
You don't have permission to access this resource.
```

### Common Causes

1. **Wrong API endpoint**: Using incorrect API address

2. **Insufficient permissions**: Current plan doesn't support this feature

3. **Regional restrictions**: Some features unavailable in certain regions

4. **Account status issues**: Account restricted

### Solutions

```bash
# Confirm API endpoint is correct
echo $ANTHROPIC_BASE_URL
# Should be: https://api.qcode.cc/api
```

1. Verify API endpoint configuration

2. Confirm plan includes required features

3. Contact support to verify permissions


### `INSUFFICIENT_BALANCE` (when it appears on a 403)

If a 403 Forbidden body contains `INSUFFICIENT_BALANCE` / `Insufficient account balance`, this is again usually a temporary upstream-channel condition relayed verbatim — **not your account being restricted**. Handle it as in the same-named subsection of the 402 section; see the [troubleshooting guide](/docs/reference/troubleshooting) for the full order.

---

## 400 - Bad Request

Incorrect request format or invalid parameters.

### Error Message

```text
Error: 400 Bad Request
The request was malformed or contained invalid parameters.
```

### Common Causes

1. **Malformed request**: Incorrect JSON format

2. **Missing parameters**: Required parameters not provided

3. **Invalid values**: Parameter values out of allowed range

4. **Encoding issues**: Special characters not properly encoded

### Solutions

```bash
# Check for special characters in input
# Ensure request content is properly formatted
claude -p "simple test"
```

1. Simplify input, exclude special characters

2. Ensure file paths use correct encoding

3. Check command parameter format

---

## 500 - Internal Server Error

Server encountered unexpected condition preventing request completion.

### Error Message

```text
Error: 500 Internal Server Error
An unexpected error occurred on the server.
```

### Common Causes

1. **Server-side bug**: API server code issue

2. **Resource exhaustion**: Server resources temporarily depleted

3. **Configuration error**: Server misconfiguration

### Solutions

```bash
# Wait and retry
sleep 60 && claude "your question"

# Use verbose mode for more info
claude --verbose
```

1. Wait a few minutes and retry

2. Check [QCode.cc](https://qcode.cc) service status

3. Contact support with error details if persistent

### E015 - Conversation Context Overflow

Triggered when the conversation context approaches the model's capacity limit (~95%). QCode.cc wraps this error as a 429 response to trigger a retry:

```text
429 {"error":{"code":"E015","message":"Internal server error"},"status":500}
```

**Solution**: See the "Long Session Overflow Prevention" section in [Context Management](/docs/usage/context-management).

---

## 503 - Service Unavailable

Server temporarily unable to handle requests, usually due to overload or maintenance.

### Error Message

```text
Error: 503 Service Unavailable
The service is temporarily unavailable. Please try again later.
```

### Common Causes

1. **Server overload**: Request volume exceeds capacity

2. **Scheduled maintenance**: Server under maintenance

3. **Resource exhaustion**: Server resources temporarily insufficient

### Solutions

```bash
# Use exponential backoff retry
for i in 1 2 4 8 16; do
  claude "your question" && break
  echo "Retrying, waiting ${i} seconds..."
  sleep $i
done
```

1. Wait a few minutes and retry

2. Use exponential backoff retry strategy

3. Check service status announcements

---

## 529 - Overloaded

Claude API-specific error code indicating API service overload.

### Error Message

```text
Error: 529 Overloaded
The API is temporarily overloaded. Please try again later.
```

### Common Causes

1. **Global usage surge**: Claude service global user spike

2. **Peak hours**: Concentrated requests during work hours

3. **Popular events**: Certain events causing usage surge

### Solutions

```bash
# Retry later
sleep 120 && claude "your question"
```

1. Wait 2-5 minutes and retry

2. Avoid peak hours (US business hours)

3. Use `/compact` to reduce token usage

> **QCode.cc Advantage**: Multi-account pool rotation mechanism effectively distributes overload pressure.

---

## Connection Timeout

Request failed to complete within the specified time.

### Error Message

```text
Error: Connection timed out
The request timed out while waiting for a response.
```

### Common Causes

1. **Unstable network**: Poor network connection quality

2. **Request too large**: Too many context tokens

3. **Task too complex**: AI processing time too long

4. **Slow server response**: High server load

### Solutions

```bash
# Test network connection
ping api.qcode.cc

# Use compact mode to reduce context
/compact
```

1. Check network connection stability

2. Use `/compact` to compress context

3. Split complex tasks into simpler ones

4. Try more stable network environment

---

## MCP Server Errors

Errors that can come from MCP server configuration or runtime.

### Symptoms

```text
MCP server "xxx" failed to start
MCP connection timed out
MCP tool execution failed
```

### Common Causes

1. **Wrong server command**: npx package name typo or not installed

2. **Missing environment variables**: the token the MCP server needs is not set

3. **Timeout**: server start-up or execution takes too long

4. **Insufficient permissions**: file system / database access denied

### Solutions

```bash
# Check server status with /mcp
/mcp

# Diagnose configuration issues with /doctor
/doctor

# Manually test whether the MCP server can start
npx -y @modelcontextprotocol/server-filesystem /tmp
```

1. Check connection status with `/mcp`

2. Run automatic diagnostics with `/doctor`

3. Verify the format of `~/.claude/settings.json` or `.mcp.json`

4. Make sure required environment variables are set (`$GITHUB_TOKEN` etc.)

5. Increase timeouts with the `MCP_TIMEOUT` and `MCP_TOOL_TIMEOUT` environment variables

---


## General Troubleshooting Steps

When encountering any error, follow these steps:

### 0. Run automatic diagnostics

```bash
# Claude Code's built-in diagnostic tool
/doctor
```

This automatically checks common configuration issues: environment variables, API connectivity, MCP server status and more.


### 1. Check Network Connection

```bash
# Test API endpoint connectivity
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models

# Test DNS resolution
nslookup api.qcode.cc
```

### 2. Verify Environment Variables

```bash
# Check all relevant environment variables
echo "BASE_URL: $ANTHROPIC_BASE_URL"
echo "AUTH_TOKEN: ${ANTHROPIC_AUTH_TOKEN:0:10}..."
```

### 3. Enable Detailed Logging

```bash
# Use verbose mode for detailed info
claude --verbose

# Or set debug mode
DEBUG=true claude
```

### 4. Test Simple Request

```bash
# Send simple test request
claude -p "say hello"
```

### 5. Check Service Status

Visit [QCode.cc](https://qcode.cc) for service status announcements.

---

## Error Handling Best Practices

### Implement Retry Mechanism

```bash
# Simple retry script
retry_claude() {
  local max_attempts=3
  local attempt=1

  while [ $attempt -le $max_attempts ]; do
    claude "$@" && return 0
    echo "Attempt $attempt failed, retrying..."
    sleep $((attempt * 2))
    ((attempt++))
  done

  echo "All attempts failed"
  return 1
}
```

### Monitor Usage

Regularly check API usage to avoid exceeding quota:

1. Login to [QCode.cc Dashboard](https://qcode.cc/dashboard)

2. View usage statistics

3. Set usage alerts

### Optimize Requests

1. **Reduce context**: Regularly use `/compact` or `/clear`

2. **Batch processing**: Split large tasks into smaller ones

3. **Avoid duplication**: Cache common results

---

## Getting Help

If the above solutions don't resolve your issue, contact QCode.cc support:

- **Live Chat**: Bottom right corner of website

- **Response Time**: 1-2 hours during business hours

- **Support Hours**: 7×14 (9:00 AM - 11:00 PM daily)

When contacting support, please provide:

1. Complete error message

2. Command executed

3. Time of occurrence

4. API Key prefix (never share full key)