# LLM API 错误码：逐个解释，逐个修复

> https://router.one/zh/llm-api-error-codes 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-08-24

客户端抛出的每个报错都对应一个 HTTP 状态码，而每个状态码指向不同的层面：你的 Key、余额、请求频率，或上游模型。这一页是 Router One OpenAI 兼容 API 及其上层 CLI 工具的错误码速查手册。先从 Dashboard → Logs 的最终请求记录开始；如需进一步排查供应商重试，请保留 request_id，支持团队可据此在运维日志中关联中间尝试。

## 速查表

每个状态码第一步先查什么：

| 状态码 | 含义 | 第一步查什么 |
| --- | --- | --- |
| 400 | 请求无效，或用错了该模型的端点 | 报错消息会点明原因：网关不提供的 Responses 特性（background、image_generation）、response_format 信封不完整，或者该模型必须走另一条路径——model '<id>' must be called via /v1/messages or /v1/chat/completions。 |
| 401 | API Key 无效或缺失 | Authorization 头需要以 `Bearer sk-…` 携带 Key——检查拼写、首尾空格，以及运行客户端的那个 shell 里环境变量是否为空。 |
| 402 | 余额不足 | 钱包余额或该 Key 的消费上限已用尽。充值，或在 Dashboard → API Keys 调高 maxSpend。 |
| 403 | 拒绝访问 | Key 已被禁用，或请求触碰了权限边界。到控制台确认 Key 状态，并核对客户端用的 base URL 是否正确。 |
| 404 | 路径或模型不存在 | 请求路径或模型 ID 不存在。从 /models 页复制精确的模型 ID——ID 区分大小写。 |
| 429 | 请求频率超限 | 触发了 Key 的 rateLimit / tokenLimitTpm 上限或上游限制。先看 Dashboard → Logs，再降低请求频率或联系支持提升限额。 |
| 500 | 服务器内部错误 | 瞬时故障。退避重试；持续出现请联系支持。 |
| 529 | 上游过载 | 模型上游饱和。若错误符合重试条件，且另一个健康供应商提供同一精确模型，Router One 可以尝试该路由；否则请采用有上限的退避重试。 |
| 超时 | 未在时限内响应 | 大 prompt 的长生成是正常的，不要给客户端设激进的超时；到最终请求指标里查看端到端延迟。 |

## 先看 trace，再动手改

Router One 的客户侧请求记录展示最终模型与供应商，以及 Token、花费、延迟和状态。Dashboard → Logs 支持按模型和日期过滤，便于判断错误是偶发还是规律。这里不展示失败供应商尝试或 fallback 链；如需排查中间尝试，请把 request_id 提供给支持团队。

## Claude Code 里的报错

Claude Code 走 Anthropic 兼容端点 https://api.router.one——注意：结尾没有 /v1。Claude Code 里的 401/403 多数来自环境变量：没设、设在了另一个 shell、或被之前登录官方服务的会话覆盖。接网关时 Claude Code 认的是 ANTHROPIC_AUTH_TOKEN；ANTHROPIC_API_KEY 不需要设置，设了反而会多弹一次授权确认。写着 model '<id>' must be called via /v1/chat/completions 的 400 则是另一回事：你配置的模型 ID 不在 Anthropic 兼容端点上服务——换成详情页列出 POST /v1/messages 的模型（Claude 系列，以及 DeepSeek V4），或者把该模型改走 /v1/chat/completions。属于鉴权问题的话，按下面设好并重启终端：

`claude-code-env.sh`

```bash
export ANTHROPIC_BASE_URL=https://api.router.one
export ANTHROPIC_AUTH_TOKEN=sk-your-router-one-key
unset ANTHROPIC_API_KEY
```

## Codex CLI 里的报错

Codex CLI 使用 Responses API 协议，而许多 OpenAI 兼容中转并没有实现它——这就是 Codex 对着它们报 404 的原因。Router One 原生支持 wire_api = "responses"。在 ~/.codex/config.toml 里配置 base_url = "https://api.router.one/v1"、wire_api = "responses"、env_key = "ROUTER_ONE_API_KEY"，并导出 ROUTER_ONE_API_KEY 环境变量。自定义 provider 下 Codex 不读 OPENAI_BASE_URL / OPENAI_API_KEY，而 requires_openai_auth 会让它完全忽略 env_key。若收到提到 background 或 image_generation 的 400 invalid_request，是网关拒绝了两项不支持的 Responses 特性：去掉 background = true，图片生成改走 /v1/images/generations 而不是 image_generation 工具；hosted 工具与 previous_response_id 在原生走 Responses 协议的模型上可用。写着 model '<id>' must be called via /v1/messages or /v1/chat/completions 的 400 是另一回事：Claude 家族的模型 ID 打到了 Responses 端点，而 Claude 不在这里服务——把 Codex 换成 GPT 系列模型或 DeepSeek V4，要用 Claude 就走 Claude Code。完整步骤见 Codex Responses API 页。

## 常见问题

### Key 看起来没问题，为什么还是 401？

三个最常见原因：环境变量设在了另一个 shell（或另一个 profile 文件）里，而不是运行客户端的那个会话；粘贴 Key 时带了尾部空格或换行；客户端读取的变量名和你设置的不一致。在启动客户端前，于同一会话里打印该变量确认。

### 402 和 429 有什么区别？

402 是钱的问题：钱包余额或 Key 的 maxSpend 上限用尽。429 是速度的问题：请求数或每分钟 token 数超过了 Key 的 rateLimit / tokenLimitTpm 或上游限制。Dashboard → Logs 的请求 trace 会告诉你命中的是哪一个。

### 遇到 5xx 需要自己写重试逻辑吗？

符合条件的 5xx 或超时，在另一个健康供应商提供同一精确模型时，可以由 Router One 重试。并非每个错误都保证重试，因此应用收到失败时仍应采用有上限的退避策略；若问题持续，请联系支持。

### 返回了 200，但 message 是空的，要不要重试？

不用——200 是一次已完成的响应，不是失败，不要自动重试。模型有时会消耗 token 却不写出正文：系统提示要求它保持沉默、推理完决定不作答，或者以 message.refusal 形式拒答。Router One 会把这样的回复原样返回，结算依据是该响应报告的 usage——循环重试只是为同一份沉默再付一次钱。先读回复里的 finish_reason、refusal 和 usage，再去调 prompt。完全没有 usage 的空响应才是故障：网关按上游错误处理，换同一模型的下一个候选重试，都不成功时返回 502。

### 同一个 Key，curl 能用，Claude Code 却 403？

curl 走的是 OpenAI 兼容端点；Claude Code 需要不带 /v1 后缀的 Anthropic 兼容 base URL，并设置 ANTHROPIC_AUTH_TOKEN。ANTHROPIC_API_KEY 不需要设置，保持未设即可。完整清单见 Claude Code 403 排查页。

### 在哪里能看到具体是哪个请求、为什么失败？

Dashboard → Logs 展示最终请求记录的状态、模型、供应商、Token 和延迟。按模型与时间范围定位后，如需检查中间失败的供应商尝试，可把 request_id 提供给支持团队查询运维日志。

### 我遇到的是 unsupported_country_region_territory 或 insufficient_quota——这是 Router One 的报错吗？

不是——这两个都来自官方 OpenAI API，不是网关。unsupported_country_region_territory 是平台边缘的地区拦截；insufficient_quota 是伪装成 429 的账单额度耗尽。两者各有专页：地区限制报错修复页和 insufficient_quota 修复页。

## 相关页面

- Claude Code 403 排查：https://router.one/zh/claude-code-403
- Codex Responses API：https://router.one/zh/codex-responses-api
- 地区限制报错修复：https://router.one/zh/unsupported-country-region-territory
- insufficient_quota 修复：https://router.one/zh/openai-insufficient-quota
- 429 深度排查指南：https://router.one/zh/blog/llm-api-429-rate-limit-fix
- 中转 API 真伪检测：https://router.one/zh/llm-api-authenticity
- 常见问题指南：https://router.one/zh/docs/guides/faq
- 产品与计费常见问题：https://router.one/zh/faq
- API 文档：https://router.one/zh/docs
- 工具调用指南：https://router.one/zh/llm-tool-calling
- 流式输出指南：https://router.one/zh/llm-streaming
- 本页规范地址：https://router.one/zh/llm-api-error-codes
- 模型与每模型 token 价格：https://router.one/zh/models（markdown：https://router.one/zh/models.md）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md