常见问题与排障
按「你看到什么 → 原因 → 怎么办」组织:401、402、任务卡住、链接 403、流式不流、中文乱码。
内容最后核对:2026-11-18
本页目录
先看这四条
九成的工单落在这里:
| 你看到 | 多半是 | 怎么办 |
|---|---|---|
401 auth.invalid_key | base 写成 /api/v1,请求被当成了控制台接口 | base 改 <网关地址>/v1。这类请求不会出现在使用日志里,因为它没有进入模型调用 |
404 model.not_found | 模型名抄了别家的,或本站没接 | GET /v1/models 看真实清单 |
402 quota.insufficient | 余额不足 | 充值。不要重试,重试一百次结果一样 |
503 channel.unavailable | 这个模型当前没有可用渠道 | 稍后重试;持续出现说明所有上游线路都不通,请联系管理员 |
报障前先抓一串 X-Request-Id(响应头里也有,request_id 在响应体里也有)。它比任何描述都精确。
鉴权类(401 / 403)
401 auth.key_missing — 没带密钥,或带了但不在认的五个位置里。检查是否把密钥写进了
Authorization 以外的自定义头;也检查中间代理有没有把它剥掉。
401 auth.invalid_key — 密钥不存在、已停用、或签发它的用户被停用。这几种情况报文相同
(不区分是刻意的:区分等于告诉攻击者「这把 key 存在但被停了」)。用户被停用时是 403 auth.account_disabled。
401 auth.key_on_console — 拿 API Key 调了 /api/**。控制台接口要登录后拿到的访问令牌,
API Key 只调 /v1/**。两个命名空间不通用。细节在鉴权与密钥。
403 model.disabled — 模型存在但已下架。别改名字,请联系管理员确认是否恢复。
403 auth.account_disabled — 账号被停用。与「密钥被停用」是两件事:换一把新 key 也没用,得找管理员。
余额与计费
为什么余额不足是 402 而不是 400。 SDK 把 4xx 当「你请求错了」,会展示成「改参数重试」; 而 402 的语义是「要钱」,主流 SDK 见到它会停止重试并提示充值。这是唯一一处刻意不用 400 的地方。
reserveQuota 不是扣款。 它是提交时的冻结。看 settleQuota + settleStatus:
SETTLED 是按实际结算、RELEASED 是失败全额释放、NONE 是还没结束。
金额怎么换算。 接口里的金额是整数,除以 GET /api/meta 返回的 quota_per_unit 就是金额,再按 balance_display 换成显示货币。这些数都从 /api/meta 取,不要写死。见计费与配额。
账单和上游发票差一点。 文本用上游 usage;上游不回报时按估算。图片按实际返回
张数、视频按实际时长。差得多时贴 X-Request-Id,日志行里有逐项计费明细可以核对。
任务类(视频 / 音乐)
一直 queued。 网关每 5 秒检查一次上游,比它更勤的轮询不会更快。真超过 10 分钟还不动,
看控制台「异步任务」页的 upstreamId:任务可能在上游排队,那不是网关能加速的。
SUBMIT_FAILED(HTTP 502)。 提交阶段就被上游拒绝了,预扣已全额释放。
响应体里有任务 id 与 error.message;按 message 改参数后重提,别原样重试。
LINK_EXPIRED。 生成本身成功了,只是产物链接到期。POST /v1/videos/{id}/refresh-url
换新链接;上游已删产物时会失败,那时只能重新生成。
下载 403。 上游的签名链通常只覆盖 GET(HEAD 会 403)。用 GET 或 GET + Range,
或者直接让我们代理:GET /v1/videos/{id}/content。
failed 但看不出原因。 四个格式的 failed 把七种原因压成了一种。看控制台任务详情里的
failCode / failDetail,或 Sora 形状里的 state 字段。
取消退不退钱。 取决于上游:有的提交即计费、取消不退,有的可退。规则由各家上游自己决定,
不由接口决定。取消后看 settleStatus 确认。
状态映射看不懂。 任务的七个状态与四种格式的对照表在视频 API, 整套异步规则在异步任务。
内容与输入
中文乱码。 请求体没声明 Content-Type: application/json; charset=utf-8,或客户端用
ISO-8859-1 解码了响应。网关自己始终按 UTF-8 输出。
token 超限(400 validation.failed,报文提到 context length)。 模型的最大上下文是上游的
硬限制,网关不截断(截断会让输出看起来「莫名其妙少了一段」)。自己裁历史消息。
工具调用(tools)在某些模型上不生效。 网关会在跨协议时转换工具定义,但目标模型必须
支持工具调用。不支持时上游会忽略 tools,表现为模型直接回答而没调函数。
modalities 带 image 却画不出图。 那个字段是「能读图」。画图要看模型有没有图片定价规则,
并且打的是图片端点。见模型与路由。
图片 b64_json 拿不到。 图片端点支持,视频端点明确 400 —— 产物可能几百 MB,不往 JSON 里塞。
流式
不流。 中间有反向代理在缓冲。网关侧已禁用压缩与缓冲;再被缓冲一层就是「等很久,然后一次吐出来」。
Nginx 上 proxy_buffering off;。排查步骤见流式输出。
流到一半断了。 没收到 [DONE] 就是中途断开(上游或网络)。计费按已发出部分折算,
不是按整段。重试前想清楚:没有幂等键的提交是第二笔钱。
只看到 reasoning_content。 那是思考过程,与正文分开发。只读 delta.content 就能忽略它。
控制台
登录后什么都看不到。 普通用户与管理员看到的菜单不同;管理员要 admin 角色,
且部分页签还需要管理员单独授权。
公告页是空的。 新建的公告是草稿,要点列表里的「发布」才会对外出现;排期的公告 到点才出现(按服务器时间 UTC 判断,不看浏览器时钟)。
时间差了 8 小时。 接口时间都是 UTC,控制台按浏览器时区渲染。自己写脚本时注意: 接口返回的时间串可能不带时区后缀,要按 UTC 解析。
「平均延迟」很大。 那个数字是「上游给出回应」的耗时:同步是整次调用、流式是首帧、 异步是提交受理。
报障模板
贴这四样,能省一轮来回:
1. X-Request-Id: req_...
2. 请求:method + 完整路径 + 请求体(密钥等敏感信息打码)
3. 响应:状态码 + 响应体
4. 时间(带时区):2026-11-18 09:12:34 +08:00
异步任务再加一条任务 id(或控制台「异步任务」页里的行)。