错误处理

所有错误都是同一种结构。

出错时 HTTP 状态码非 2xx，响应体里只有一个 error 对象：

json

{
  "error": {
    "message": "Insufficient credits: this request needs 60 credits. Top up and try again.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_credits"
  }
}

字段

字段	说明
message	给人看的英文说明。不要用它做程序分支——文案会调整
type	错误大类，见下表
code	具体原因。程序分支请判断这个字段
param	出问题的参数名，无法定位到具体参数时为 null

常见错误

HTTP	code	含义与处理
401	missing_api_key	没带 Authorization 头，或格式不是 Bearer sk-xxx
401	invalid_api_key	密钥无效、已停用或已删除。三种情况合并同一句文案，不区分
400	invalid_request	参数有问题，看 message。例如 prompt 为空、图生视频没给图
402	insufficient_credits	算力不足。充值后重试，重试前建议先查 /v1/credits
429	rate_limit_exceeded	调用过于频繁，退避后重试
429	concurrency_limit_reached	并发或每日额度受限，稍后重试
404	not_found	任务不存在，或不属于当前密钥所属账号
502	generation_failed	同步生图时全部出图失败，算力已自动退还
504	generation_timeout	同步生图等待超时。任务仍在跑、算力不退，用 message 里的任务 id 去 /v1/tasks/{id} 取结果
500	internal_error	服务端异常。可重试，若持续出现请联系我们

异步提交成功后如果渲染失败，不会走这里的错误结构——那时接口是 200，任务对象的 status 为 failed，原因在 error 字段里。只有同步生图会把失败直接抛成 502。