文档 / 参考手册 / 错误码速查

错误码速查

按错误码快速查找原因和解决方案

错误码参考

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

错误码速查表

错误码 类型 简述 严重程度
400 客户端错误 请求格式错误 低
401 认证错误 API Key 无效 中
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. 账户配额耗尽：当日/当月配额已用完

解决方案

立即措施：

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

解决方案

立即措施：

# 检查网络连接
curl -I https://asia.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：

# 检查环境变量
echo $ANTHROPIC_AUTH_TOKEN

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

处理步骤：

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

  2. 确认订阅未过期

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

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://asia.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. 编码问题：特殊字符未正确编码

解决方案

# 检查输入内容是否包含特殊字符
# 确保请求内容格式正确
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. 如持续发生，联系技术支持并提供错误详情

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 asia.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 -I https://asia.qcode.cc/api

# 测试 DNS 解析
nslookup asia.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）

← 上一篇
常见报错速查
下一篇 →
计费与套餐