LLM API 错误码：逐个解释，逐个修复
客户端抛出的每个报错都对应一个 HTTP 状态码，而每个状态码指向不同的层面：你的密钥、余额、请求频率，或上游模型。这一页是 Router One OpenAI 兼容 API 及其上层 CLI 工具的错误码速查手册。先从 Dashboard → Logs 的最终请求记录开始；如需进一步排查供应商重试，请保留 request_id，支持团队可据此在运维日志中关联中间尝试。
速查表
每个状态码第一步先查什么：
| 状态码 | 含义 | 第一步查什么 |
|---|---|---|
| 401 | API Key 无效或缺失 | Authorization 头需要以 `Bearer sk-…` 携带密钥——检查拼写、首尾空格，以及运行客户端的那个 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-env.sh
export ANTHROPIC_BASE_URL=https://api.router.one export ANTHROPIC_API_KEY=sk-your-router-one-key export ANTHROPIC_AUTH_TOKEN=sk-your-router-one-key
Codex CLI 里的报错
Codex CLI 使用 Responses API 线协议，而许多 OpenAI 兼容中转并没有实现它——这就是 Codex 对着它们报 404 的原因。Router One 原生支持 wire_api = "responses"。通过 ~/.codex/config.toml 把 Codex 指到 https://api.router.one/v1，并在同一个 shell 里设置 OPENAI_API_KEY。完整步骤见 Codex Responses API 页。
常见问题
- Key 看起来没问题，为什么还是 401？
- 三个最常见原因：环境变量设在了另一个 shell（或另一个 profile 文件）里，而不是运行客户端的那个会话；粘贴密钥时带了尾部空格或换行；客户端读取的变量名和你设置的不一致。在启动客户端前，于同一会话里打印该变量确认。
- 402 和 429 有什么区别？
- 402 是钱的问题：钱包余额或 Key 的 maxSpend 上限用尽。429 是速度的问题：请求数或每分钟 token 数超过了 Key 的 rateLimit / tokenLimitTpm 或上游限制。Dashboard → Logs 的请求 trace 会告诉你命中的是哪一个。
- 遇到 5xx 需要自己写重试逻辑吗？
- 符合条件的 5xx 或超时，在另一个健康供应商提供同一精确模型时，可以由 Router One 重试。并非每个错误都保证重试，因此应用收到失败时仍应采用有上限的退避策略；若问题持续，请联系支持。
- 同一个 Key，curl 能用，Claude Code 却 403？
- curl 走的是 OpenAI 兼容端点；Claude Code 需要不带 /v1 后缀的 Anthropic 兼容 base URL，且要在 ANTHROPIC_API_KEY 之外同时设置 ANTHROPIC_AUTH_TOKEN。完整清单见 Claude Code 403 排查页。
- 在哪里能看到具体是哪个请求、为什么失败？
- Dashboard → Logs 展示最终请求记录的状态、模型、供应商、Token 和延迟。按模型与时间范围定位后，如需检查中间失败的供应商尝试，可把 request_id 提供给支持团队查询运维日志。