错误码

所有 4xx / 5xx 响应都遵循相同的 envelope。code 是 ERR_*前缀的稳定字符串，随 message 一起返回。

Envelope

{
  "error": {
    "message": "human-readable description",
    "type": "authentication_error",
    "code": "ERR_AUTH_FAILED",
    "request_id": "req_01JABC..."
  }
}

type 沿用 OpenAI 大类（invalid_request_error、authentication_error、permission_error、rate_limit_error、api_error）；code 是网关稳定常量。

常见 code

认证 (401)

• ERR_AUTH_FAILED · sk-gw- key 无效（不存在 / 已禁用 / 格式错）
• ERR_AUTH_REQUIRED · 接口需要 Bearer 但请求没带
• ERR_BAD_CREDENTIALS · 控制台登录密码错（含未知邮箱）
• ERR_KEY_DISABLED · key 被管理员禁用

权限 (403)

• ERR_KEY_SCOPE · 此 key 不在请求模型的 scope 内
• ERR_ACCOUNT_SUSPENDED · 账户被暂停

请求格式 (400)

• ERR_BAD_BODY · JSON 解析失败
• ERR_BAD_MODEL · model 不存在
• ERR_BAD_PASSWORD · 密码长度不合法（10-72）
• ERR_BAD_EMAIL · 邮箱格式不合法
• ERR_BAD_RANGE · /usage/summary 当前只支持 range=24h
• ERR_BAD_CURSOR · 翻页 cursor 不合法
• ERR_PROTOCOL_MISMATCH · OpenAI body 发到 /messages 或反之
• ERR_INVALID_REQUEST · 视频任务参数不合法（分辨率、画幅、时长、seed、帧率、role，或 prompt 里写错的 -- 后缀）

计费 (402)

• ERR_INSUFFICIENT_FUNDS · 余额不足，未向上游 forward

限流 (429)

• ERR_RATE_LIMITED · 滑动窗口超限（默认 60 RPM）
• ERR_ACCOUNT_LOCKED · 控制台密码连续 5 次错误，锁 15 分钟

404

• ERR_KEY_NOT_FOUND · 操作了不存在或不属于自己的 key
• ERR_ORDER_NOT_FOUND · 充值订单不存在或不属于自己
• ERR_NOT_FOUND · 视频任务不存在，或不属于自己。 两者故意不区分——告诉你"存在但不是你的"就泄露了 id 空间
• ERR_UNKNOWN_MODEL · 该 model 不由本网关提供

服务端 (5xx)

• ERR_INTERNAL · 网关内部错；带 request_id 联系客服
• ERR_DB · 数据库不可用
• ERR_UPSTREAM · 上游 5xx 透传。视频建任务被上游拒绝（含限流）也是这个 code，502； 未建成的任务不计费
• ERR_PERSIST · 503 · 视频任务已提交到上游但本地没记上。带 request_id 联系客服

运营开关 (503)

运营侧临时停用，message 里带停用原因。

• ERR_SUPPLIER_SUSPENDED · 上游整体停用
• ERR_MODEL_SUSPENDED · 该模型停用
• ERR_KEY_SUSPENDED · 该 key 停用

四个开关按「供应商 → 模型 → 客户 → key」的顺序判定，同时命中时报最宽的那个： 上游事故是最宽的原因，先报它，客服才不会拿着「账号被停」去查一个其实是上游挂了的问题。

追踪

每个错误都带 request_id（也在响应 Header X-Request-Id）。 在控制台 Logs 页顶部搜索栏可以直接定位。