错误码

公开接口通常以 HTTP 状态码表示结果，并返回 OpenAI 兼容的错误信封。 message 是排查入口，type 和 code 可能随路由或上游通道变化。

{
  "error": {
    "message": "model is required",
    "type": "invalid_request_error",
    "code": "bad_request_body"
  }
}

响应头中的 request ID（如果返回）应与错误消息一起记录，便于支持人员定位。 日志中可以记录 request ID、HTTP 状态码、路由和模型，但绝不要记录 Authorization 值或 API Key。

HTTP 状态码

状态码	常见原因	客户端下一步
400	JSON 无效、缺少 model/prompt、字段类型错误、模型不支持参数，或请求的路由/模型组合无效。	不要重试原请求；根据 error.message 修正请求，先移除可选字段，并用 /v1/models 核对模型。
401	没有提供 Bearer 凭证、凭证格式错误或 API Key 已失效。	检查 Authorization: Bearer <YOUR_API_KEY> 是否完整，重新读取环境变量；不要把 Key 放进 URL。
403	凭证有效但没有调用该模型或路由的权限，或账号策略拒绝了请求。	联系账号管理员确认权限、模型范围和额度策略；不要通过反复重试绕过权限。
404	URL 路径错误、模型/任务/产物不存在，或结果地址已失效。	检查公共 Base URL 和路径；任务接口使用返回的 task_id，不要猜测 ID；临时结果 URL 失效时重新提交任务。
429	触发速率限制、并发限制或可用额度不足。	读取 Retry-After（若有），降低并发并使用指数退避；确认额度后再继续。
500	服务端内部错误或本地处理失败。	记录 request ID 后稍后重试一次；若持续发生，把脱敏后的请求、时间和 request ID 提交支持。
502	上游模型通道返回无效响应、网关连接失败或上游暂时不可用。	使用指数退避重试，逐步增加等待时间；持续失败时保存 request ID 并联系支持。
503	服务暂时过载、无可用通道或正在维护。	使用指数退避并降低并发；不要高频轮询。恢复后再提交。

指数退避只适用于 429、502 和 503，例如等待 1、2、4、8 秒并设置 最大次数。400、401、403 和通常的 404 属于请求或权限问题，盲目重试 不会修复原因。

任务请求的特殊情况

提交视频或其他异步任务后，如果客户端在响应到达前断线，不要立即再次提交： 服务端可能已经接受并开始处理，重复提交会产生重复任务或重复费用。先根据 已知的 task_id 查询状态；如果连 task_id 都没有，记录时间、路由和 request ID，联系支持确认接受状态。