错误码与排错

先按顺序过一遍下面的清单，大多数问题在前三步就能找到。

排查顺序

1. 地址：Anthropic 系工具填 https://1zheai.com，OpenAI 系填 https://1zheai.com/v1。见 Base URL 与鉴权。
2. API 密钥（API key）：是否完整（没有多余空格、换行）、是否已被删除、是否填进了正确的字段。
3. 余额：控制台里余额是否充足。
4. 模型 ID：是否和支持的模型里的完全一致。
5. 网络：关掉代理直连再试一次。
6. 还不行：拿一条最小的 curl 复现（见下），把回包和时间发给我们。

最小复现

curl -i https://1zheai.com/v1/messages \
  -H "x-api-key: sk-你的Key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

-i 会把状态码和响应头一起打印出来，排查时很有用。

错误码速查

状态码	常见原因	怎么办
400	请求体有问题：参数名错、字段类型错、max_tokens 超过模型上限、带了上游不认的 beta 字段	看 message 里指出的字段；Claude Code 的情况见下文”Extra inputs are not permitted”
401	API 密钥无效、已删除、已禁用、已过期、自身额度用完，或没带、放错了请求头	回包都是 Invalid token，逐项检查；Anthropic 原生用 x-api-key 或 Authorization: Bearer
403	账户余额不足（billing_error / insufficient_quota）；这个 API 密钥没开通该模型；请求 IP 不在这个 API 密钥的白名单里（都是 permission_error）	充值，或在「API 密钥」页编辑这个 API 密钥的模型限制和 IP 白名单
404	路径不对，或模型不存在 / 当前不可用	Invalid URL 核对地址；not_found_error / model_not_found 核对模型 ID 和可用列表
413	请求体太大	减少一次发送的内容，大文件分段
429	上游临时限流。目前我们不对 API 密钥设速率限制	稍后重试，批量任务加指数退避
503	模型存在但暂时没有健康的上游服务，或服务临时故障	稍后重试；持续失败时提供请求 ID 联系支持
500 / 502	网关或上游临时故障	稍后重试；持续出现发邮件到 [email protected]
504	请求超时	长输出用流式；调大客户端超时
529	上游 Anthropic 过载（overloaded_error）	等几秒重试，或临时换一个模型

Anthropic 官方错误类型（invalid_request_error、authentication_error、rate_limit_error、overloaded_error 等）的完整含义见官方 Errors 文档。

上游返回的错误，状态码和 message 原样带回，message 末尾加上本次请求的 request id。走 /v1/messages 时外层是官方的 {"type":"error","error":{...}} 结构，error.type 按状态码填官方类型；走 /v1/chat/completions 时是 OpenAI 的 {"error":{...}} 结构。

实测回包

下面是 2026-10-15 对 /v1/messages 实测的真实回包。走 /v1/chat/completions 时内容相同，外层没有 "type":"error"，error 里多一个 code 字段。

401 API 密钥无效、禁用、过期或额度用完

401 API 密钥无效、禁用、过期或额度用完

{"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"}

403 账户余额不足

403 账户余额不足

{"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"}

403 API 密钥没开通该模型

403 API 密钥没开通该模型

{"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"}

403 IP 不在白名单

403 IP 不在白名单

{"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"}

400 上游参数错误

400 上游参数错误

{"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"}

404 路径不存在

404 路径不存在

{"error":{"message":"Invalid URL (POST /v1/nonexistent)","type":"invalid_request_error","param":"","code":""}}

模型不存在或不可用时的 404 说明见支持的模型。回包里的 request id 对应你的这一次请求，反馈问题时带上它。

按症状排查

401 / Invalid token

• API 密钥复制时多了空格或换行，重新复制一次。
• API 密钥已在控制台删除或禁用，或者已过期、自身额度已用完。这几种情况的回包都是同一句 Invalid token。
• Claude Code 里同时设置了 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN，而其中一个是旧值：两个只留一个，推荐 ANTHROPIC_AUTH_TOKEN。
• settings.json 的 env 会覆盖终端里 export 的同名变量，改了终端变量不生效时，检查 ~/.claude/settings.json。

404 / Invalid URL

先看错误类型：not_found_error 或 model_not_found 要检查模型 ID 与可用列表。Invalid URL 则检查 /v1：OpenAI SDK、Cursor、Cline（OpenAI Compatible）要填到 https://1zheai.com/v1；Claude Code 和 Anthropic SDK 只填 https://1zheai.com，填了 /v1 会变成 /v1/v1/messages。

403 / error code: 1010

回包只有 error code: 1010 这一行、没有 JSON，说明请求在到达网关前被拦下了。目前已知用 Python 标准库 urllib 直接发请求会遇到（它默认的 User-Agent 是 Python-urllib/3.x）。在请求头里加一个自己的 User-Agent，或者改用官方 SDK、requests、httpx。

429 太多请求

目前不对 API 密钥设速率限制。收到 429，通常是上游负载高，稍后重试即可。批量任务建议加指数退避：失败后等一段时间再试，每次等待时间翻倍，并自己用队列控制并发。

529 / overloaded_error

上游 Anthropic 暂时过载，和你的 API 密钥、余额无关。等几秒重试；赶时间的话临时换到同系列的另一个模型。

超时、流式中途断开

• 长回答尽量用流式（"stream": true），不容易被中间网络设备掐断。
• Claude Code 可以用 API_TIMEOUT_MS 调大超时，默认 600000（10 分钟）。
• 开着代理的话，先关代理试一次，很多断流来自代理节点。

Claude Code：直接进了登录界面

说明 Claude Code 没读到你的 API 密钥。在 Claude Code 里运行 /status，看 base URL 和凭据来源两行；为空就回到 Claude Code 接入检查环境变量或 settings.json。

Claude Code：Extra inputs are not permitted / context_management 报 400

Claude Code 会在请求里带一些实验性的 beta 字段，严格的上游不认就会报 400。设置下面的环境变量关掉它们（来自 Claude Code 官方 LLM gateway 文档）：

bash

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

余额充足但调用失败

• 如果只有某个模型失败，可能是该模型暂时不可用、ID 写错，或者这个 API 密钥设了模型限制（403 This token has no access to model …）。
• 如果全部失败且是 401，看看这个 API 密钥是不是设了额度上限并且已经用完，或者已经过期。在「API 密钥」页的「额度 ($)」和「过期」两列能看到。
• 其它情况看上面的错误码表。

还是没解决

发邮件到 [email protected]，附上时间、模型 ID、你用的工具和版本、curl -i 的完整输出（删掉 API 密钥）。