错误码参考

Claude Code 常见错误码及解决方案

需要 API Key？ 前往注册 →·端点与 Base URL →

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

错误码速查表¶

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

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

错误表现¶

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

常见原因¶

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

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

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

额度用完不是 429：日额度、总额度、周限额用完时返回的是 402（insufficient_quota），见本页 402 额度用完。

解决方案¶

立即措施：

# 等待 30-60 秒后重试
sleep 60 && claude "你的问题"

长期措施：

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

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

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

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. 请求超时：响应时间超过网关限制

解决方案¶

立即措施：

# 检查网络连接
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models

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

长期措施：

1. 检查本地网络稳定性

2. 尝试切换网络环境

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

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

QCode.cc 优势：多地域部署，CDN 加速，自动故障转移。

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：

# 检查环境变量
echo $ANTHROPIC_AUTH_TOKEN

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

处理步骤：

1. 登录 QCode.cc 控制台 检查 API Key 状态

2. 确认订阅未过期

3. 如被封禁，联系客服处理

402 - 需要付费（Payment Required）¶

402 有两种含义，先看响应体：error.type 是 insufficient_quota 就是额度用完（见 额度用完）；否则是模型服务暂时拒绝（见 服务暂时拒绝）。

额度用完（insufficient_quota）¶

响应是 HTTP 402，error.type 为 insufficient_quota，code 说明是哪一种额度用完了：

响应体示例（总额度用完）：

{
  "error": {
    "type": "insufficient_quota",
    "message": "已达到总费用限制 ($100)",
    "code": "total_cost_limit_exceeded"
  },
  "currentCost": 100.42,
  "costLimit": 100
}

message 括号里的金额（如 $100）是这项额度的上限，总额度那条是累计上限，不是剩余额度。

这类 402 不会因为重发而消失，请不要写重试循环；按上表恢复额度即可。

Key 过期返回的是 401，不是 402（{"error":"Invalid API key","message":"API key has expired"}），见上面的 401 一节。

服务暂时拒绝¶

响应体里没有 insufficient_quota 时，这次请求是被模型服务链路拒绝的。这通常不是你的 Key 或配置的问题 —— 同一把 Key 在同一时段发往其它模型的请求往往照常成功。

错误表现¶

Error: 402 Payment Required

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

常见原因¶

1. 该模型的服务暂时不可用：这类 402 由服务链路返回，QCode 网关把状态原样传给你

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

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

4. 与你的余额无关：这类 402 不是余额或套餐额度耗尽造成的；额度用完的 402 带有 insufficient_quota，见上一节 额度用完

解决方案¶

① 换一个模型（最有效）

# 会话内切换
/model sonnet

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

② 换一个接入域

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

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

三个接入域用同一把 Key，切换无需改动其它配置。见 接入点与 API 格式。

③ 不要写紧密重试循环

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

④ 持续出现就联系客服

带上出现时间、模型 id、接入域，联系在线客服或发邮件到 hi@qcode.cc。

INSUFFICIENT_BALANCE / Insufficient account balance¶

有的 402/403 响应会带着 "code":"INSUFFICIENT_BALANCE", "message":"Insufficient account balance" 这样的 JSON。这不代表你的 QCode 余额不足——它是服务链路某个环节的临时状况被原样透传，与你的账户无关。你自己的额度用完时，响应体里是 insufficient_quota 加 *_cost_limit_exceeded（见上面的 额度用完）。

处置：稍后重试 / 换一个模型 / 换一个接入域（上面 ①–③ 步都适用）；持续出现请带 request id 联系客服。整体排查顺序见 故障排查指南。

403 - 权限错误（Forbidden）¶

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

错误表现¶

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

常见原因¶

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

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

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

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

解决方案¶

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

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

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

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

INSUFFICIENT_BALANCE（出现在 403 时）¶

如果 403 Forbidden 的响应体里带着 INSUFFICIENT_BALANCE / Insufficient account balance，这通常同样是后端的临时状况被透传，不是你的账户被限制。按 402 一节同名小节的办法处理；排查顺序见 故障排查指南。

400 - 请求错误（Bad Request）¶

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

错误表现¶

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

常见原因¶

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

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

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

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

解决方案¶

# 检查输入内容是否包含特殊字符
# 确保请求内容格式正确
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. 配置错误：服务器配置问题

解决方案¶

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

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

1. 等待几分钟后重试

2. 检查 QCode.cc 服务状态

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

E015 - 对话上下文溢出¶

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

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

解决方案：详见 上下文管理 的「长会话溢出预防」章节。

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

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

错误表现¶

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

常见原因¶

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

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

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

解决方案¶

# 使用指数退避重试
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. 热门事件：某些事件导致用量突增

解决方案¶

# 稍后重试
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. 服务器响应慢：服务器负载高

解决方案¶

# 测试网络连接
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. 权限不足：文件系统/数据库访问权限不足

解决方案¶

# 使用 /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. 运行自动诊断¶

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

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

1. 检查网络连接¶

# 测试 API 端点连通性
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models

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

2. 验证环境变量¶

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

3. 启用详细日志¶

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

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

4. 测试简单请求¶

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

5. 检查服务状态¶

访问 QCode.cc 查看服务状态公告。

错误处理最佳实践¶

实现重试机制¶

# 简单重试脚本
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 控制台

2. 查看用量统计

3. 设置用量提醒

优化请求¶

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

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

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

获取帮助¶

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

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

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

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

联系时请提供：

1. 完整的错误信息

2. 执行的命令

3. 发生时间

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

企业团队版 →