# 错误码参考

本文档详细介绍 Claude Code 使用过程中可能遇到的各种错误码及其解决方案。

## 错误码速查表

| 错误码 | 类型 | 简述 | 严重程度 |
|--------|------|------|----------|
| 400 | 客户端错误 | 请求格式错误 | 低 |
| 401 | 认证错误 | API Key 无效 | 中 |
| 402 | 通道错误 | 上游通道暂时拒绝服务 | 中 |
| 403 | 权限错误 | 访问被拒绝 | 中 |
| 429 | 限流错误 | 请求过于频繁 | 中 |
| 500 | 服务器错误 | 内部错误 | 高 |
| 502 | 网关错误 | 上游服务不可用 | 高 |
| 503 | 服务不可用 | 服务暂时过载 | 高 |
| 529 | API 过载 | Claude API 过载 | 高 |

---

## 429 - 请求频率超限（Too Many Requests）

这是最常见的错误之一，表示短时间内发送了过多请求。

### 错误表现

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

### 常见原因

1. **请求过于频繁**：连续快速发送多个请求

2. **并发请求过多**：同时运行多个 Claude Code 实例

3. **Token 用量达到限制**：短时间内消耗大量 token

4. **账户配额耗尽**：当日/当月配额已用完

### 解决方案

**立即措施**：
```bash
# 等待 30-60 秒后重试
sleep 60 && claude "你的问题"
```

**长期措施**：

1. 减少请求频率，避免连续快速发送

2. 使用 `/compact` 命令压缩上下文

3. 将大任务拆分为小任务分批执行

4. 考虑升级到更高配额的套餐

> **QCode.cc 优势**：专业负载均衡，多账号池分散请求压力，有效降低 429 错误发生率。

---

## 502 - 网关错误（Bad Gateway）

表示网关或代理服务器从上游服务器收到无效响应。

### 错误表现

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

### 常见原因

1. **上游服务暂时不可用**：Anthropic API 服务器问题

2. **网络连接中断**：请求过程中连接断开

3. **代理服务器问题**：中间节点故障

4. **请求超时**：响应时间超过网关限制

### 解决方案

**立即措施**：
```bash
# 检查网络连接
curl -I https://api.qcode.cc/api

# 等待后重试
sleep 30 && claude "你的问题"
```

**长期措施**：

1. 检查本地网络稳定性

2. 尝试切换网络环境

3. 使用 VPN 或更稳定的网络

4. 如持续发生，联系技术支持

> **QCode.cc 优势**：多地域部署，CDN 加速，自动故障转移，保障 99.9% 可用性。

---

## 401 - 认证失败（Unauthorized）

API Key 无效或未提供有效的认证信息。

### 错误表现

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

### 常见原因

1. **API Key 错误**：复制时遗漏字符或包含多余空格

2. **API Key 过期**：订阅已过期

3. **API Key 被禁用**：违规使用导致封禁

4. **环境变量未设置**：`ANTHROPIC_AUTH_TOKEN` 未配置

### 解决方案

**验证 API Key**：
```bash
# 检查环境变量
echo $ANTHROPIC_AUTH_TOKEN

# 确认格式正确（以 cr_ 开头）
# 正确示例：cr_xxxxxxxxxxxxxxxxxxxx
```

**处理步骤**：

1. 登录 [QCode.cc 控制台](https://qcode.cc/dashboard) 检查 API Key 状态

2. 确认订阅未过期

3. 如被封禁，联系客服处理（QCode.cc 提供即时替换服务）

---

## 402 - 需要付费（Payment Required）

上游通道拒绝了这次请求。**这通常不是你的 Key 或配置的问题** —— 同一把 Key 在同一时段发往其它模型的请求往往照常成功。

### 错误表现

```
Error: 402 Payment Required
```

在 Claude Code 里通常表现为请求直接失败、没有任何回复内容；在脚本或 SDK 里则是 HTTP 402。

### 常见原因

1. **上游通道暂时不可用**：QCode 网关自身不产生 402，它把上游返回的状态原样传给你

2. **集中在特定模型**：同一时段里，某个模型的 402 比例可能很高，而其它模型完全正常

3. **与接入域有关**：不同接入域走的上游链路不同，402 出现的概率可能相差很大

4. **与你的余额无关**：账户余额和套餐配额耗尽不会返回 402，那种情况的提示是「已达到每日费用限制」，见 [常见问题（FAQ）](/docs/reference/faq)

### 解决方案

**① 换一个模型（最有效）**

```bash
# 会话内切换
/model sonnet

# 或启动时指定
claude --model claude-sonnet-5
```

**② 换一个接入域**

```bash
# 中国大陆
export ANTHROPIC_BASE_URL=https://asia.qcode.cc/api

# 全球（Route 53 自动就近）
export ANTHROPIC_BASE_URL=https://api.qcode.cc/api
```

四个接入域用同一把 Key，切换无需改动其它配置。见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

**③ 不要写紧密重试循环**

402 不会因为立刻重发而消失，密集重试只会放大问题。请改用指数退避，或直接切换模型 —— 参见本页「错误处理最佳实践」。

**④ 持续出现就联系客服**

带上出现时间、模型 id、接入域，联系[在线客服](javascript:void(Tawk_API.toggle()))或发邮件到 [hi@qcode.cc](mailto:hi@qcode.cc)。

---

## 403 - 权限错误（Forbidden）

请求被服务器拒绝，通常是权限不足。

### 错误表现

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

### 常见原因

1. **API 端点错误**：使用了错误的 API 地址

2. **功能权限不足**：当前套餐不支持该功能

3. **区域限制**：某些功能在特定地区不可用

4. **账户状态异常**：账户被限制

### 解决方案

```bash
# 确认 API 端点配置正确
echo $ANTHROPIC_BASE_URL
# 应为：https://api.qcode.cc/api
```

1. 检查 API 端点配置是否正确

2. 确认套餐是否包含所需功能

3. 联系客服确认权限配置

---

## 400 - 请求错误（Bad Request）

请求格式不正确或参数无效。

### 错误表现

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

### 常见原因

1. **请求格式错误**：JSON 格式不正确

2. **参数缺失**：必需参数未提供

3. **参数值无效**：参数值超出允许范围

4. **编码问题**：特殊字符未正确编码

### 解决方案

```bash
# 检查输入内容是否包含特殊字符
# 确保请求内容格式正确
claude -p "简单测试"
```

1. 简化输入内容，排除特殊字符

2. 确保文件路径使用正确的编码

3. 检查命令参数格式

---

## 500 - 服务器内部错误（Internal Server Error）

服务器遇到意外情况，无法完成请求。

### 错误表现

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

### 常见原因

1. **服务器端 Bug**：API 服务器代码问题

2. **资源不足**：服务器资源暂时耗尽

3. **配置错误**：服务器配置问题

### 解决方案

```bash
# 等待后重试
sleep 60 && claude "你的问题"

# 使用 verbose 模式获取更多信息
claude --verbose
```

1. 等待几分钟后重试

2. 检查 [QCode.cc](https://qcode.cc) 服务状态

3. 如持续发生，联系技术支持并提供错误详情

### E015 - 对话上下文溢出

当对话上下文接近模型容量上限（~95%）时触发。QCode.cc 将此错误包装为 429 响应以触发重试：

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

**解决方案**：详见 [上下文管理](/docs/usage/context-management) 的「长会话溢出预防」章节。

---

## 503 - 服务不可用（Service Unavailable）

服务器暂时无法处理请求，通常是过载或维护。

### 错误表现

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

### 常见原因

1. **服务器过载**：请求量超过服务器容量

2. **计划维护**：服务器正在维护

3. **资源耗尽**：服务器资源暂时不足

### 解决方案

```bash
# 使用指数退避重试
for i in 1 2 4 8 16; do
  claude "你的问题" && break
  echo "重试中，等待 ${i} 秒..."
  sleep $i
done
```

1. 等待几分钟后重试

2. 使用指数退避策略重试

3. 检查服务状态公告

---

## 529 - API 过载（Overloaded）

Claude API 特有的错误码，表示 API 服务过载。

### 错误表现

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

### 常见原因

1. **全球用量激增**：Claude 服务全球用户激增

2. **高峰时段**：工作时间请求集中

3. **热门事件**：某些事件导致用量突增

### 解决方案

```bash
# 稍后重试
sleep 120 && claude "你的问题"
```

1. 等待 2-5 分钟后重试

2. 避开高峰时段（美国工作时间）

3. 使用 `/compact` 减少 token 用量

> **QCode.cc 优势**：多账号池轮换机制，有效分散过载压力。

---

## 连接超时（Connection Timeout）

请求在规定时间内未能完成。

### 错误表现

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

### 常见原因

1. **网络不稳定**：网络连接质量差

2. **请求内容过大**：上下文 token 过多

3. **任务过于复杂**：AI 处理时间过长

4. **服务器响应慢**：服务器负载高

### 解决方案

```bash
# 测试网络连接
ping api.qcode.cc

# 使用 compact 模式减少上下文
/compact
```

1. 检查网络连接稳定性

2. 使用 `/compact` 压缩上下文

3. 将复杂任务拆分为简单任务

4. 尝试更稳定的网络环境

---

## MCP 服务器错误

MCP 服务器配置或运行时可能出现的错误。

### 错误表现

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

### 常见原因

1. **服务器命令错误**：npx 包名拼写错误或未安装

2. **环境变量缺失**：MCP 服务器所需的 Token 未设置

3. **超时**：服务器启动或执行时间过长

4. **权限不足**：文件系统/数据库访问权限不足

### 解决方案

```bash
# 使用 /mcp 命令查看服务器状态
/mcp

# 使用 /doctor 诊断配置问题
/doctor

# 手动测试 MCP 服务器是否能启动
npx -y @modelcontextprotocol/server-filesystem /tmp
```

1. 使用 `/mcp` 查看服务器连接状态

2. 使用 `/doctor` 运行自动诊断

3. 检查 `~/.claude/settings.json` 或 `.mcp.json` 配置格式

4. 确保所需的环境变量已设置（`$GITHUB_TOKEN` 等）

5. 增加超时时间：设置 `MCP_TIMEOUT` 和 `MCP_TOOL_TIMEOUT` 环境变量

---

## 通用排查步骤

遇到任何错误时，按以下步骤排查：

### 0. 运行自动诊断

```bash
# Claude Code 内置的诊断工具
/doctor
```

这会自动检查环境变量、API 连接、MCP 服务器状态等常见配置问题。

### 1. 检查网络连接

```bash
# 测试 API 端点连通性
curl -I https://api.qcode.cc/api

# 测试 DNS 解析
nslookup api.qcode.cc
```

### 2. 验证环境变量

```bash
# 检查所有相关环境变量
echo "BASE_URL: $ANTHROPIC_BASE_URL"
echo "AUTH_TOKEN: ${ANTHROPIC_AUTH_TOKEN:0:10}..."
```

### 3. 启用详细日志

```bash
# 使用 verbose 模式查看详细信息
claude --verbose

# 或设置调试模式
DEBUG=true claude
```

### 4. 测试简单请求

```bash
# 发送简单测试请求
claude -p "说你好"
```

### 5. 检查服务状态

访问 [QCode.cc](https://qcode.cc) 查看服务状态公告。

---

## 错误处理最佳实践

### 实现重试机制

```bash
# 简单重试脚本
retry_claude() {
  local max_attempts=3
  local attempt=1

  while [ $attempt -le $max_attempts ]; do
    claude "$@" && return 0
    echo "尝试 $attempt 失败，重试中..."
    sleep $((attempt * 2))
    ((attempt++))
  done

  echo "所有尝试均失败"
  return 1
}
```

### 监控用量

定期检查 API 用量，避免超出配额：

1. 登录 [QCode.cc 控制台](https://qcode.cc/dashboard)

2. 查看用量统计

3. 设置用量提醒

### 优化请求

1. **减少上下文**：定期使用 `/compact` 或 `/clear`

2. **分批处理**：将大任务拆分为小任务

3. **避免重复**：缓存常用结果

---

## 获取帮助

如果以上方案无法解决问题，请联系 QCode.cc 技术支持：

- **在线客服**：网站右下角聊天窗口

- **响应时间**：工作时间 1-2 小时内

- **支持时间**：7×14（每天 9:00-23:00）

联系时请提供：

1. 完整的错误信息

2. 执行的命令

3. 发生时间

4. API Key 前缀（不要提供完整 Key）