错误码与排查

本页只整理当前接口文档和教程里已经提到的问题，不额外编造具体错误码。没有明确错误码时，用“可能表现为 400 / 401 / 403 / 404 / 超时”等方式描述。

常见问题总表

类别	可能表现	排查方向
鉴权失败	401	检查 API Key 是否缺失、是否完整保留 `sk-`、是否使用 `Authorization: Bearer sk-...`。
令牌不可用	401 / 403	检查令牌是否被禁用、过期、额度不足或触发 IP 限制。
余额不足	403 或请求失败	到钱包查看余额、充值记录和消费变化。
模型不存在或无权限	403 / 404	用查询可用模型确认当前令牌是否能看到目标模型。
地址填写错误	404	检查 Base URL 是否符合工具要求。Codex/OpenAI 兼容工具通常填 `https://api.routescope.ai/v1`；Claude Code 通常填 `https://api.routescope.ai`。
参数错误	400	检查是否混用了协议字段，例如 OpenAI Chat 使用 `messages`，Gemini 使用 `contents[].parts[]`，Claude Messages 需要 `max_tokens`。
Claude Code experimental betas	400	可能出现 `context_management: Extra inputs are not permitted`，按工具页关闭 experimental betas。
请求超时	超时	高分辨率图像、长视频任务、长文本或上游响应慢时可能出现。异步任务请查询任务状态。
限流	429 或请求失败	RPM、TPM、并发限制以后台配置和接口返回为准。

优先检查：

请求头是否写成 Authorization: Bearer sk-your-token。
是否复制了完整密钥，且没有删除 sk- 前缀。
令牌是否被禁用、过期或触发 IP 限制。
客户端字段是否填对，例如 Codex 的 auth.json 使用 OPENAI_API_KEY，Claude Code 使用 ANTHROPIC_AUTH_TOKEN。

如果请求失败但 Key 和模型都正确，回到钱包查看：

模型相关错误常见原因：

建议先调用：

curl https://api.routescope.ai/v1/models \
  -H "Authorization: Bearer sk-your-token"

Gemini 原生模型列表使用：

curl https://api.routescope.ai/v1beta/models \
  -H "Authorization: Bearer sk-your-token"

不要混用不同协议：

协议	正确结构
OpenAI Chat Completions	`POST /v1/chat/completions`，请求体包含 `model` 和 `messages`。
Claude Messages	`POST /v1/messages`，请求体包含 `model`、`messages`、`max_tokens`。
Gemini Generate Content	`POST /v1beta/models/{model}:generateContent`，请求体使用 `contents[].parts[]`。
Imagen Predict	`POST /v1beta/models/{model}:predict`，请求体使用 `instances` 和 `parameters`。
OpenAI 风格图像编辑	`POST /v1/images/edits`，OpenAI 风格编辑需使用 `multipart/form-data` 上传原图文件。
Doubao Seedream 编辑	`POST /v1/images/edits`，参考图通过 JSON 请求体中的 `image` 字段传入。

以下情况可能表现为超时：

视频和异步图像任务建议保存任务 ID，然后通过任务查询接口或任务日志查看状态和失败原因。

RPM、TPM、并发限制等具体值以后台配置和接口返回为准。当前接口文档没有统一列出具体限流错误码，因此不要在业务中假设固定错误码。