免费开始

错误码

网关生成的 OpenAI 格式错误响应遵循以下 envelope。code 是 ERR_*前缀的稳定字符串，随 message 一起返回。上游透传响应和 Anthropic 原生响应可能使用不同格式。

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_PROTOCOL_UNSUPPORTED · 模型与接口不匹配。 视频模型不能用于聊天接口，请改用 POST /api/v1/video/tasks或 POST /api/v3/contents/generations/tasks。 不扣费，原请求直接重试不会成功；Anthropic 接口返回invalid_request_error，调用记录使用同一错误码。
  • 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_MODEL_NOT_FOUND · 聊天接口未找到该模型的路由定义。 请核对 model ID；若模型仍在公开目录内，请带 request_id 联系客服。 模型存在但暂无可用通道时返回 503；模型与接口不匹配时返回 400。
  • ERR_KEY_NOT_FOUND · 操作了不存在或不属于自己的 key
  • ERR_ORDER_NOT_FOUND · 充值订单不存在或不属于自己
  • ERR_NOT_FOUND · 视频任务不存在，或不属于自己。 两者故意不区分——告诉你"存在但不是你的"就泄露了 id 空间
  • ERR_UNKNOWN_MODEL · 该 model 不由本网关提供

服务端 (5xx)

  • ERR_UPSTREAM_DOWN · 502 · 聊天上游连接失败或响应中断。 参数错误、模型与接口不匹配、网关内部错误不属于此类。
  • ERR_UPSTREAM_TIMEOUT · 504 · 聊天上游响应超时
  • ERR_MODEL_UNAVAILABLE · 503 · 模型存在，但暂时没有可用通道。 请稍后重试，无需修改 model ID。
  • ERR_UPSTREAM_STREAM · 上游在流内返回了无法进一步分类的错误。 HTTP 状态可能已是 200；请根据流内错误判断调用结果。
  • 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」的顺序判定，同时命中时报最宽的那个： 上游事故是最宽的原因，先报它，客服才不会拿着「账号被停」去查一个其实是上游挂了的问题。

聊天上游拒绝请求

调用记录中的 ERR_UPSTREAM_400、ERR_UPSTREAM_404、ERR_UPSTREAM_422 等表示上游拒绝了已路由的请求， 需要结合错误详情检查参数或模型配置。ERR_UPSTREAM_401 / ERR_UPSTREAM_403 表示上游鉴权或权限拒绝， 不等于用户的平台 API key 无效；请携带 request_id 联系客服。ERR_UPSTREAM_429 表示上游限流，请遵循响应中的 Retry-After（若有）退避重试。 这些错误不会累计供应商故障计数。

这里的 ERR_UPSTREAM_数字 是调用记录中的诊断码。上游原始错误响应可能保留自己的 code； Anthropic Messages 接口保留原生错误格式。流内错误也会写入调用记录。

追踪

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