错误处理

错误使用 OpenAI 兼容结构。客户端应以 HTTP 状态码、error.type、error.code 和请求 ID作为判断依据，不解析自然语言消息。

{
  "error": {
    "message": "The request could not be completed.",
    "type": "upstream_error",
    "code": "media_generation_failed",
    "request_id": "req_xxx"
  }
}

常见状态码

状态码	含义	客户端处理
400	参数或模型能力不匹配	修正请求，不自动重试
401	API Key 无效或缺失	检查并轮换密钥
403	分组、模型或任务无权限	检查账号权限，不自动重试
404	任务或资源不存在	检查任务 ID和所有者
409	任务状态冲突	重新查询任务状态
429	额度或请求频率限制	按 Retry-After 退避
500	服务内部错误	有限次数指数退避
502 / 503 / 504	上游或网络暂时不可用	有限次数指数退避

重试建议

• 只重试幂等查询、资源下载以及明确返回可重试错误的提交请求。
• 生成请求在网络中断时结果可能未知。没有幂等键前，不要无限自动重放，以免重复计费。
• 对 429 优先读取 Retry-After；否则采用带抖动的指数退避。
• 单次请求设置连接超时，异步任务设置独立的整体截止时间。

支持信息

反馈问题时提供：SourcesData 请求 ID、时间、公开任务 ID、模型和 HTTP 状态码。不要提交完整 API Key、上游信息、用户输入素材或下载 token。