排错指南：Claude Code & API 报错速查

常见报错排查指南

一句话：先看错误码——401 是 API Key 不对，403 是余额不足或封禁，429 是限流（用指数退避重试），5xx 是 Anthropic 上游短暂不可用（直接重试），400 是请求参数错（自己改）。

调用 Claude API 时遇到错误，先看错误码 —— 大多数问题不需要联系客服，自助就能解决。本文按错误码分类，给出原因、解决步骤、以及什么情况下才需要联系客服。

401 Unauthorized：认证失败

典型响应：

{
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  }
}

可能原因：

1. API Key 拼写错误（漏一位、多空格、字符替换）
2. API Key 已被禁用或已删除
3. 请求头格式不对，没用 x-api-key 或 Authorization: Bearer
4. 用了 Anthropic 官方的 Key（应该用 CodeGateway 颁发的 sk-cg- 开头的 Key）

解决步骤：

1. 登录 Dashboard → API 密钥 页面，确认 Key 是 sk-cg- 开头
2. 检查 Key 状态是否为"启用"
3. 复制 Key 时不要复制到多余空格 —— 用 Dashboard 的"复制"按钮更稳妥
4. 在 .env 或环境变量里设置：

export ANTHROPIC_AUTH_TOKEN="sk-cg-YOUR_KEY"
export ANTHROPIC_BASE_URL="https://api.codegateway.dev"

何时联系客服：所有自助排查都做了仍 401，且 Dashboard 显示 Key 是启用状态。

403 Forbidden：账号被禁用 / 余额不足

典型响应：

{
  "error": {
    "type": "permission_denied",
    "message": "insufficient balance"
  }
}

可能原因：

1. 余额不足（最常见）：账户余额已扣完
2. 账号被风控临时禁用（极少数）
3. 当前模型不在你的订阅范围内（暂时无该限制，仅留作未来扩展）

解决步骤：

1. Dashboard → 概览 页面查看实时余额
2. 余额接近零或为零 → 账单 页面充值
3. 若余额充足仍 403 → 联系客服

何时联系客服：余额 ≥ $1 但仍 403。

429 Too Many Requests：触发速率限制

典型响应：

{
  "error": {
    "type": "rate_limit_error",
    "message": "rate limit exceeded for your plan"
  }
}

可能原因：

CodeGateway 当前对所有用户统一限流 60 RPM。429 通常是短时间集中调用触发。

当前限流策略：所有用户统一 60 RPM（每分钟 60 个请求）。TPM (Tokens Per Minute) 字段在配置中预留，当前不强制执行。

CodeGateway 暂未推出付费套餐分级（Starter / Pro / Team 等）。后续推出时会在公告中通知并更新本文档。

解决步骤：

1. 指数退避重试：第一次失败后等 1s、第二次 2s、第三次 4s，最多 3 次。这是 Anthropic 官方推荐策略。
2. 批处理：如果是离线任务（如批量分析日志、批量生成测试用例），可以加 await sleep(N) 限速，让 RPM 平稳分布
3. 升级套餐：如果业务峰值长期接近上限，到 Dashboard 升级到更高 RPM 套餐

代码示例（Node.js 指数退避）：

async function withRetry<T>(fn: () => Promise<T>, maxAttempts = 3): Promise<T> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn()
    } catch (e: any) {
      if (e.status !== 429 || attempt === maxAttempts) throw e
      const delay = 1000 * 2 ** (attempt - 1) // 1s, 2s, 4s
      await new Promise(r => setTimeout(r, delay))
    }
  }
  throw new Error('unreachable')
}

何时联系客服：业务峰值需要超出 Team 套餐的 RPM/TPM —— 我们可以为企业用户单独配置上限。 快速上手配置

500 / 502 / 503：上游服务异常

典型响应：

{
  "error": {
    "type": "api_error",
    "message": "upstream error"
  }
}

可能原因：

1. 502/503：Anthropic 上游服务短暂不可用（最常见，通常几分钟内恢复）
2. 500：CodeGateway 网关本身异常（极少，监控会立刻告警）

解决步骤：

1. 直接重试：5xx 是临时错误，无脑指数退避重试通常能成功
2. 不要修改请求内容：5xx 不是你的请求有问题，重试相同请求即可
3. 持续 5 分钟仍 5xx → 检查 Anthropic Status
4. Anthropic 状态正常但 CodeGateway 仍 5xx → 联系客服（非常少见）

何时联系客服：连续 10 分钟以上 5xx，且 Anthropic Status 显示一切正常。

400 Bad Request：请求参数错误

典型响应：

{
  "error": {
    "type": "invalid_request_error",
    "message": "messages: missing required field"
  }
}

可能原因：

1. 缺必填字段（如 model, messages, max_tokens）
2. 字段格式错误（如 messages 不是数组）
3. 模型名拼写错误（如写成 claude-sonnet-4 而不是 claude-sonnet-4-6）
4. max_tokens 超出该模型上限
5. 角色顺序错误（必须 user → assistant 交替，不能连续两个 user）

解决步骤：

1. 仔细看 message 字段 —— Anthropic 错误信息很具体，通常会指出哪个字段有问题
2. 对照 Anthropic 官方文档 检查请求格式
3. 用 curl 单独发一次最小请求验证基础参数

最小可工作请求示例：

curl https://api.codegateway.dev/v1/messages \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hi"}]
  }'

跨模型不兼容的 thinking / reasoning 字段（首调 400 高发）

换模型时如果还带着上一个模型的思考 / 推理参数，上游会直接 400 invalid_request。三类最常见：

• thinking.*（Claude 扩展思考）：

• thinking.type=disabled 在 claude-*-5-5（自适应思考）上不被接受——模型关不掉思考，会 400。可改用 thinking.type=between_tools 或 thinking.type=adaptive + output_config.effort。

• thinking.type=enabled 在不支持经典扩展思考的模型上同样 400。

• reasoning_effort / context_management：OpenAI / Responses 系参数，打到 Anthropic Messages 通路或不认识它的模型时，上游报 Extra inputs are not allowed。换模型时请删掉，或改成目标模型文档里的等价字段。

实测错误（2026-10-13）：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "thinking.type.disabled is not supported on claude-sonnet-5-5. Use thinking.type.between_tools (lowest) or thinking.type.adaptive + output_config.effort. The model cannot disable thinking."
  }
}

若响应头出现 x-codegateway-translation-warnings，说明网关已剥离部分装饰性参数（不会静默关掉真正的 thinking——语义相关的思考请求仍会明确 400）。

anthropic-version 请求头只能填单个版本号

• 不要逗号拼接多值：写成 "2023-06-01, 2023-01-01" 会 400。

• 正确写法：anthropic-version: 2023-06-01

实测错误（2026-10-13，首调 400 样本同形）：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "anthropic-version: \"2023-06-01, 2023-01-01\" is not a valid version"
  }
}

role: system 在两条通路上的差异

• Anthropic Messages（POST /v1/messages）：系统提示词放在顶层 system 参数，不要写成 messages 里的 {"role":"system"}。

• OpenAI Chat Completions（POST /v1/chat/completions）：{"role":"system"} 合法，放在 messages 数组开头即可。

Messages 通路实测错误（2026-10-13）：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages.0: use the top-level 'system' parameter for the initial system prompt; the directive-only form (content: [] with output_config) is accepted at any position"
  }
}

何时联系客服：通常不需要 —— 400 是参数问题，自己修。

context window exceeded：超出上下文长度

典型响应：

prompt is too long: <X> tokens > <max> tokens

可能原因：

输入 + 期望输出 token 数超过模型上下文窗口（Sonnet 4.6 = 200K tokens，Opus = 200K，Haiku = 200K）。

解决步骤：

1. 用 Anthropic tokenizer 在本地预估 token 数
2. 截断历史消息：只保留最近 N 轮对话
3. 摘要替代：把长文档先用 Haiku 摘要，再把摘要传给 Sonnet/Opus
4. 分段处理：长文档分块，每块独立处理然后合并结果

网络层错误：connection reset / timeout

如果错误不带 HTTP 状态码（如 ECONNRESET、ETIMEDOUT），是网络层问题：

1. 检查本机网络（能否 ping 通 api.codegateway.dev）
2. 检查代理设置（如果你在公司网络）
3. SSE 流式请求需要长连接，确认中间没有 60s 超时的代理

还是搞不定？

进 Dashboard → 右下角反馈组件，附上：

• 错误码 + 错误响应原文（json）
• 请求示例（去掉 API Key）
• 出现时间（精确到分钟）

我们会在 24 小时内给出诊断结论。

常见问题

Q：401 但 API key 看起来是对的，先查什么？

A：按这个顺序排查 —— 1) Dashboard 看 key 状态是否启用；2) 复制时多没多空格 / 漏字符（用「复制」按钮，不要手敲）；3) header 名字是 x-api-key 或 Authorization: Bearer（不是 ANTHROPIC_AUTH_TOKEN）；4) 自助步骤都做了仍 401 → 联系客服。

Q：持续 5xx 是 CodeGateway 问题还是 Anthropic？

A：先看 Anthropic Status（status.anthropic.com）。如果 Anthropic 有事，等就好（CodeGateway 透传上游错误）；如果 Anthropic 全绿但你这边连续 10 分钟 5xx，那才是 CodeGateway 的问题，立即联系客服。

Q：我的请求是流式（SSE），有时候中途断流，怎么办？

A：先看是不是公司网络的代理 / 防火墙杀长连接（最常见）—— 把 *.codegateway.dev 加白名单 + 关闭中间代理的连接超时设置。CodeGateway 在 Cloudflare 边缘加了 15 秒 keep-alive 心跳，如果心跳被中间链路 strip 了，长流就会断。

相关文档

• API 使用教程 — 基础调用示例
• 统一倍率详解 — 计费机制
• API Key 安全最佳实践 — 密钥管理

参考资料

• Anthropic API 错误码官方文档
• Anthropic 状态页
• Anthropic 限流官方说明