GrooRoute Pro 常见报错排查：401、403、404、413、429、5xx
调用 GrooRoute Pro 报错时，先看 HTTP 状态码，再看返回 JSON 里的 error.code 和 error.message。401 是 API Key 的问题，403 是权限或额度，404 多半是地址里的 /v1 写错，413 是请求体过大，429 是限流，5xx 是网关或上游出错、可以稍后重试。报错信息的末尾带有中文说明和处理办法，照着做通常就能解决。
报错长什么样
接口返回的错误是一段 JSON：
{
"error": {
"message": "… | … | 这次请求没有带 API Key。请在请求头里带上 \"Authorization: Bearer sk-…\"… (request id: …)",
"type": "new_api_error",
"code": "missing_api_key"
}
}message 由三段组成，用 | 隔开：原始信息、英文说明、中文说明，最后是这次请求的 request id。下面各节引用的都是中文说明那一段的原文。
401：API Key 的问题
| error.code | 网关的说明 | 处理办法 |
|---|---|---|
missing_api_key | 这次请求没有带 API Key。 | 在请求头里带上 Authorization: Bearer <API Key>。用环境变量存密钥时，确认变量是在当前终端里设置的。 |
invalid_api_key | API Key 未被接受（不存在、过期、额度用完或禁用）。 | 到控制台的「API 密钥」里查看这把 Key 的状态，或重新生成一把。 |
网关对不存在、过期、额度用完和被禁用的 Key 返回的是同一个 invalid_api_key，不会告诉调用方具体是哪一种，需要到控制台里看。
403：权限或额度不够
| 网关的说明 | 处理办法 |
|---|---|
| 这把 API Key 无权发起这次请求（IP 白名单、分组或 Key 状态不允许）。 | 在控制台检查这把 Key 的 IP 白名单、分组和状态，或新建一把 Key。 |
| 这把 API Key 所在的分组对你的账户不可用。 | 在控制台把 Key 换到可用分组，或新建一把 Key。 |
| 这个模型不在这把 Key 的分组或模型范围内。 | 用 GET /v1/models 查看可用模型，或在控制台调整 Key 的分组或模型范围。 |
| 钱包余额不足以完成这次请求。 | 在控制台充值后重试。 |
| 订阅卡额度已用完或不够支付这次请求。 | 等卡额度重置或购买新卡；计费方式为只用订阅卡的，如需用余额继续，请改为订阅优先并充值。 |
| 订阅卡额度和钱包余额都不够支付这次请求。 | 充值或购买新卡后重试。 |
| 订阅卡额度已用完或不够支付这次请求，这张卡不能用余额补足。 | 等卡额度重置或购买新卡。 |
| 你的订阅卡不包含这个模型或分组，只能用钱包余额支付，钱包余额不足。 | 充值，或改用订阅卡包含的模型。 |
| 当前计费方式为只用订阅卡，但没有卡能用于这次请求。 | 购买包含该模型的卡，或把计费方式改为订阅优先并充值。 |
| 账户余额或 Key 额度不足以完成这次请求。 | 在控制台充值，或提高这把 Key 的额度后重试。 |
| 体验卡和订阅卡只能用于自营模型。 | 充值后会自动用余额调用这个模型；计费方式为只用订阅卡的，请先改为订阅优先或余额优先。 |
| 账号不存在或被禁用。这种情况没有专用的说明，附的是通用客户端错误说明。 | 看 message 第一段的原始信息；对账号状态有疑问请联系客服。 |
表里除最后一行外的情况，要先改 Key 的设置、充值、换卡或改计费方式（订阅卡也可以等额度重置），改之前原样重试得到的还是同一个结果。余额或额度不足时，报错的第一段写明是钱包、订阅卡还是两者都不够，以及剩余多少、本次需预留多少。403 的其他情形以报错里的说明为准。
404：接口路径不对
网关自己拒绝时，说明是：「GrooRoute 上没有这个接口路径。」处理办法是：「请使用 /v1/chat/completions、/v1/responses 或 /v1/messages，并确认接口地址没有重复写 /v1（不要出现 /v1/v1）。」原始信息会写出实际收到的方法和路径，例如 Invalid URL (POST /v1/v1/chat/completions)，对照它就能看出地址哪里写错了。如果错误来自上游（error.type 为上游错误），说明会换成「上游模型服务对这次请求返回了错误」那一条。
- 路径是 /v1/v1/…：base_url 里已经有
/v1，客户端又补了一次。把 base_url 改成不带/v1的https://grooroute.xyz。 - 路径是 /v1/chat/completions/responses 之类：把完整的接口地址填进了 base_url。base_url 只填到
https://grooroute.xyz/v1为止。 - 路径只有 /v1：在浏览器里打开了接口地址，或客户端的「测试连接」直接访问了它。这是接口地址，不是网页，不影响正常调用。
少写 /v1 的情况不会报 404：对 /chat/completions、/responses 等几个固定路径，网关会补上 /v1 再处理，并在响应头 X-GrooRoute-Notice 里提示。完整说明见API 地址要不要带 /v1。
413：请求体过大
网关自己拒绝时，说明是：「请求体过大（本网关单次上限 N MB，上游线路可能更低）。」其中 N 是网关当前的上限，报错里写的是实际数字。处理办法是：「请开新会话，或压缩对话、去掉较大的图片和附件后再发；原样重试仍会失败。」上游返回 413 时附的也是这一条。
它通常出现在很长的会话里：每一轮请求都带着之前的全部对话，越积越大，最后超过了请求体的上限。命令行工具遇到 413 时如果自动重发同一个请求，结果还是 413，所以要开一个新会话，而不是等一会儿再试。
429：请求过多
网关自己拒绝时，说明是：「当前请求过多或并发过高。」处理办法是：「请按 Retry-After 头的秒数等待后重试，降低并发，或升级套餐等级。」如果错误来自上游（error.type 为上游错误），说明会换成「上游模型服务对这次请求返回了错误」那一条。
响应里带有 Retry-After 头时，它的值是建议等待的秒数。程序里遇到 429 应当等待后再重试，不要立刻重发。
5xx：网关或上游出错
| 网关的说明 | 处理办法 |
|---|---|
你所在分组当前没有这个模型可用。（model_not_found，状态码 503） | 先核对模型名拼写，再用你的 Key 调用 GET /v1/models 查看可用模型，或在控制台换模型/分组；刚才还能用的话一分钟后重试。 |
这个模型的上游线路当前全忙或在冷却中。（get_channel_failed 等） | 请稍后重试或换模型；GrooRoute 网站的服务状态页可查看各线路状态。 |
| 上游模型服务对这次请求返回了错误。 | 几秒后重试或换模型；持续失败请联系客服并附 request id。 |
| 上游模型服务没有及时响应。 | 请重试、缩短提示词，或换一个模型。 |
| 上游返回的内容不完整或格式异常（例如流式输出中途断开）。 | 请重试；持续失败请联系客服并附 request id。 |
| 网关处理这次请求时出现内部错误。 | 请几秒后重试；持续失败请联系客服并附 request id。 |
联系客服时，请附上报错信息末尾的 request id。客服邮箱见页面底部。
返回的是网页，不是 JSON
如果客户端报「解析失败」，而返回内容是一段 HTML，说明请求没有落到接口上，而是落到了网站页面。原因通常是 base_url 填的不是接口地址。OpenAI 兼容客户端的 base_url 应当是 https://grooroute.xyz/v1。
常见问题
报错信息里的 request id 有什么用？
它标识这一次请求。持续失败需要联系客服时，把它一起发来，方便定位。
哪些错误原样重试没有用？
401、403、404 和 413 要先改 Key、权限、地址或请求内容；429 按 Retry-After 等待后再试；5xx 可以几秒后重试。
为什么报错信息有中英文两段？
API 客户端通常不带语言偏好，网关在原始信息后面同时附上英文和中文的说明与处理办法。
返回的是网页而不是 JSON，怎么回事？
请求没有落到接口上，通常是地址不对。按「API 地址要不要带 /v1」一篇核对 base_url。
最后更新：