加载中…
Claude API 调用遇到 401 Unauthorized、429 Too Many Requests、500 Internal Server Error 怎么办？本文按错误码分类，给出原因、解决步骤、是否需要联系客服。
一句话：先看错误码——401 是 API Key 不对，403 是余额不足或封禁，429 是限流（用指数退避重试），5xx 是 Anthropic 上游短暂不可用（直接重试），400 是请求参数错（自己改）。
调用 Claude API 时遇到错误，先看错误码 —— 大多数问题不需要联系客服，自助就能解决。本文按错误码分类，给出原因、解决步骤、以及什么情况下才需要联系客服。
典型响应：
{
"error": {
"type": "authentication_error",
"message": "invalid x-api-key"
}
}可能原因：
x-api-key 或 Authorization: Bearersk-cg- 开头的 Key）解决步骤：
sk-cg- 开头.env 或环境变量里设置：export ANTHROPIC_AUTH_TOKEN="sk-cg-YOUR_KEY"
export ANTHROPIC_BASE_URL="https://api.codegateway.dev"何时联系客服：所有自助排查都做了仍 401，且 Dashboard 显示 Key 是启用状态。
典型响应：
{
"error": {
"type": "permission_denied",
"message": "insufficient balance"
}
}可能原因：
解决步骤：
何时联系客服：余额 ≥ $1 但仍 403。
典型响应：
{
"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 等）。后续推出时会在公告中通知并更新本文档。
解决步骤：
await sleep(N) 限速，让 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 —— 我们可以为企业用户单独配置上限。 快速上手配置
典型响应：
{
"error": {
"type": "api_error",
"message": "upstream error"
}
}可能原因：
解决步骤：
何时联系客服：连续 10 分钟以上 5xx，且 Anthropic Status 显示一切正常。
典型响应：
{
"error": {
"type": "invalid_request_error",
"message": "messages: missing required field"
}
}可能原因：
model, messages, max_tokens）messages 不是数组）claude-sonnet-4 而不是 claude-sonnet-4-6）max_tokens 超出该模型上限解决步骤：
message 字段 —— Anthropic 错误信息很具体，通常会指出哪个字段有问题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"}]
}'何时联系客服：通常不需要 —— 400 是参数问题，自己修。
典型响应：
prompt is too long: <X> tokens > <max> tokens可能原因：
输入 + 期望输出 token 数超过模型上下文窗口（Sonnet 4.6 = 200K tokens，Opus = 200K，Haiku = 200K）。
解决步骤：
如果错误不带 HTTP 状态码（如 ECONNRESET、ETIMEDOUT），是网络层问题：
进 Dashboard → 右下角反馈组件，附上：
我们会在 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 了，长流就会断。