常见问题排查

调用失败时，先看返回的错误信息，再对照本页。大部分问题在这里就能自己解决。

本页按真实发生频率排序——最前面两类占了实际失败的一多半，而且它们都不是你的配置问题。

先分清：谁的问题

上游返回的错误（最常见）

这一类的共同点：平台已经把请求正常转发出去了，是上游模型服务商那边出了问题。 你的密钥、余额、参数都没错。

上游限流

典型错误原文：

You exceeded your current quota, please check your plan and billing details.
You have exceeded your current request limit.
Rate limit exceeded. Please wait and try again, or upgrade your API plan.
Request rate increased too quickly.

上游模型服务商对平台账号做了限流，通常发生在你或其他用户短时间内大量调用某个热门模型时。

怎么办：

1. 加指数退避重试——这是最有效的一招。撞到限流立刻重试只会让情况更糟。
2. 确认密钥用的是「智能路由」。智能路由带熔断，某条线路被限流会自动切到其他线路；如果你手动指定了供应商，就等于放弃了这个能力。
3. 持续大量出现时，换一个同能力的模型分散压力，或联系客服。

上游服务故障

典型错误原文：

bad response status code 524
upstream connect error or disconnect/reset before headers
service unavailable
internal server error
status_code=500, The product is not activated...

上游服务商临时故障、超时或网关异常。

怎么办：重试。524 和 upstream connect error 通常是上游响应太慢或连接被断开，长输出的请求更容易撞上——可以改用流式返回（stream: true），既降低超时概率也改善体感。

请求参数错误

典型错误原文：

invalid_request_error
invalid_parameter_error
unsupported_parameter
unknown_parameter
status_code=404, Resource not found

请求体本身有问题。按这个顺序查：

1. Content-Type: application/json 有没有带；
2. JSON 语法是否合法（多余逗号、引号不配对）；
3. 必填字段是否齐全（model、messages）；
4. 参数是否被目标模型支持——unsupported_parameter / unknown_parameter 说明你传了这个模型不认识的参数。不同厂商的模型支持的参数不完全一样，把 OpenAI 的参数原样传给其他厂商的模型时最容易撞到；
5. Resource not found 多数是模型名写错或调用了该模型不支持的接口（比如把对话模型调成了图片接口）。

额度类

额度不足

账户余额不够了。到钱包页充值或兑换，到账后立即恢复，无需等待。

如果你确认刚充过值，看一眼钱包页的限时赠额卡片——赠额到期回收会让总余额下降。详见限时赠额。

该令牌额度已用尽

这把密钥自身的额度上限用完了（不是账户余额不足）。编辑该密钥调高额度，或打开无限配额。

两者的区别见钱包与充值。

鉴权类

无效的令牌 / 未提供令牌

平台没能识别你的密钥。

• 检查请求头格式是否正确：Authorization: Bearer sk-xxxxxxxx，Bearer 后有一个空格。
• 检查密钥有没有多余的空格、换行或引号——从聊天工具复制粘贴时经常带上不可见字符。
• 检查密钥是不是已经被删除了。删除不可恢复，只能新建一把。
• 确认你请求的域名和创建密钥的站点是同一个。在 A 站点创建的密钥不能在 B 站点使用。

该令牌已过期

密钥超过了设定的过期时间。到 API 密钥页编辑该密钥，延长过期时间或设为永不过期。

该令牌状态不可用

密钥被禁用了。到 API 密钥页重新启用。

请求被拒绝，但密钥看起来正常

检查这把密钥有没有配 IP 白名单。

1.2.3.4
5.6.7.8
203.0.113.0/24

还要注意：如果你的服务在容器、云函数或有出口网关的环境里，实际出口 IP 可能和你以为的不一样，而且可能会变。不确定时先清空白名单验证，确认是这个原因后再补上正确的网段。

模型与线路类

该令牌无权访问模型 xxx

这把密钥设置了模型限制，而你调用的模型不在允许列表里。编辑密钥，把该模型加进去，或者清空模型限制。

该令牌无权访问任何模型

模型限制配置有问题，允许列表实际是空的。编辑密钥重新选择模型，或清空该限制。

未指定模型名称，模型名称不能为空

请求体里缺 model 字段，或者字段名拼错了。

分组 xxx 下模型 yyy 无可用渠道

你请求的模型，在当前这条供应商线路下没有可用资源。可能的原因和对策：

1. 模型名拼错了 — 最常见。到模型广场复制准确的模型名，注意大小写、连字符和版本号。
2. 这条线路不支持该模型 — 换一个供应商，或把密钥的供应商路由改成智能路由 → 智能自动，让系统自己找有资源的线路。
3. 该模型确实临时不可用 — 稍后重试；持续出现请联系客服。

无权访问该分组

你的账户没有使用这条供应商线路的权限。用密钥里默认可选的供应商即可；如果你确实需要某条特定线路，联系客服。

当前分组上游负载已饱和，请稍后再试

这条线路当前排队已满。稍后重试，或改用智能路由让系统切换到其他可用线路。

平台侧频率限制

您已达到请求数限制：N 分钟内最多请求 M 次

降低并发、加上指数退避重试即可。

还有一条总请求数限制，它把失败的请求也算在内——如果你的代码在快速重试失败请求，很容易把这个额度耗光，反而让恢复变得更慢。遇到限流时一定要退避，不要立刻重试。

无效的请求，...

平台在转发前就判定请求不合法（区别于上游返回的 invalid_request_error）。检查 Content-Type、JSON 语法与必填字段，详见请求参数错误。

结果不符预期

明明调用成功，但扣费比预想多

见用量与日志 → 消费排查。最常见的原因是输入 tokens 远超预期——长上下文、整篇文档塞进 prompt、多轮对话累积历史。

返回的图片链接打不开

上游返回的原始图片链接有效期通常很短。需要长期保存请自行落库，或配置自有存储自动转存。

响应很慢

• 在使用日志里看这次请求的耗时和重试次数。重试多说明上游不稳定。
• 把密钥的路由策略改成速度优先试试。
• 长输出本身就慢，流式返回（stream: true）能显著改善体感。

还是没解决

联系站点客服，并提供：

1. 请求 ID（在使用日志里展开失败的那条）；
2. 出错的大致时间；
3. 完整的错误信息原文；
4. 用的是哪把密钥（名称即可，不要发密钥本身）。