AI API — 错误返回与排查指引说明

/v1/chat/completions 错误返回

• 格式（非流式与流式出错时统一为 JSON 错误，可能直接关闭连接）：

{
  "error": {
    "message": "未指定模型名称，模型名称不能为空",
    "type": "new_api_error",
    "code": "invalid_request"
  }
}

• 常见原因与排查：
  • 参数缺失/不合法：未提供 model、messages 为空或 content 类型错误。
  • 鉴权失败：Authorization 头未携带 Bearer Token 或令牌无效（401）。
  • 权限问题：令牌无权访问指定模型/分组，或分组已禁用（403）。
  • 频率限制：达到模型或全局频率上限（429）。
  • 模型不可用：当前分组下该模型无可用渠道（503）。
  • 上游异常：网络错误或上游响应错误（5xx，message 可能为“请求上游地址失败”或“bad response status code ”）。

---

/v1/images/generations 错误返回

• 格式：与 chat 接口一致，返回 error 对象。

{
  "error": {
    "message": "size 不合法，合法示例：1024x1024",
    "type": "new_api_error",
    "code": "invalid_request"
  }
}

• 常见原因与排查：
  • 参数缺失/不合法：未提供 model；size/quality/response_format 取值与模型不匹配。
  • 鉴权/权限：与 chat 相同（401/403）。
  • 频率限制：达到请求上限（429）。
  • 模型不可用或渠道不可用（503）。
  • 上游异常（5xx）。

---

/v1/realtime（WebSocket）错误返回

• 握手阶段（HTTP）失败：返回 JSON 错误，与 REST 类一致（例如 401/403/400）。

{
  "error": {
    "message": "无效的 API Key",
    "type": "new_api_error",
    "code": "access_denied"
  }
}

• 会话阶段（WS 事件）失败：以事件形式返回，type 为 "error"。

{
  "type": "error",
  "event_id": "evt_123456",
  "error": {
    "message": "请求格式不合法或上游错误",
    "type": "new_api_error",
    "code": "invalid_request"
  }
}

• 常见原因与排查：
  • 握手头部不正确：Sec-WebSocket-Protocol 不符合要求或未声明（400）。
  • 鉴权失败：Authorization 令牌无效（401）。
  • 权限/配额限制（403/429）：无权访问模型或达到频率/额度限制。
  • 上游异常或网络问题（5xx）：连接中断或响应错误。

---

POST /v1/video/generations 错误返回（任务提交）

• 格式（与 REST 不同）：任务接口统一返回 TaskError 结构。

{
  "code": "insufficient_user_quota",
  "message": "用户额度不足, 剩余额度: 0"
}

• 其他示例：

{ "code": "invalid_request", "message": "缺少 prompt 或 image" }
{ "code": "pre_consume_token_quota_failed", "message": "预扣费额度失败, 用户剩余额度: 10, 需要预扣费额度: 20" }
{ "code": "do_request_failed", "message": "请求上游地址失败" }

• 常见原因与排查：
  • 参数校验失败：缺少必要字段（如 model、prompt 与 image 至少其一）。
  • 渠道/模型不可用：目标模型在当前分组下无可用渠道（可能返回 503 或 5xx）。
  • 额度/预扣失败（403）：insufficient_user_quota、pre_consume_token_quota_failed。
  • 上游网络/响应错误（5xx）：do_request_failed、bad_response_status_code 等。
  • 服务端持久化失败（500）：insert_task_failed。

---

GET /v1/video/generations/:task_id 错误返回（任务查询）

• 格式：同为 TaskError 结构。

{ "code": "task_not_exist", "message": "task_not_exist" }

• 其他示例：

{ "code": "get_task_failed", "message": "数据库查询失败或服务端异常" }

• 常见原因与排查：
  • 任务不存在/ID 错误：task_not_exist（400）。
  • 服务端查询异常：get_task_failed（500）。
  • 上游实时同步失败：一般不影响返回结构，优先返回本地记录；如需实时状态，请稍后重试。

---

排查建议总览：

• 核对 Authorization: Bearer 是否正确；令牌是否具备模型/分组访问权限。
• 检查是否命中频率限制（429）或额度不足（403）；必要时降低调用频率或提升额度。
• 确认模型在当前分组下可用；如返回 503，请在控制台为该模型配置有效渠道。
• 对参数进行自检：model、messages（chat）、size/quality/response_format（images）、prompt/image（video）。
• 若提示“请求上游地址失败”或“bad response status code ”，请检查上游服务可用性与网络连接。
• 任务查询请确保 task_id 正确；如为新提交任务，稍候再查以避免短暂的未同步状态。

---