错误码
HTTP 状态码、错误信封与任务级失败。
两类失败，别混淆
- 请求级失败（提交/查询本身出错）：返回非 2xx HTTP 状态码 + OpenAI 风格错误信封。
- 任务级失败（图没生成出来）：
GET /v1/tasks/{task_id}仍返回 HTTP 200，但data.status = failed，详情在data.error（见 查询任务）。
请求级错误信封：
HTTP 状态码
| HTTP | 含义 | 怎么办 |
|---|---|---|
400 | 参数不合法（张数、比例、参考图超 15 张等） | 检查请求体 |
401 | 未提供 / 无效的 API 密钥（含密钥被删除或过期） | 检查 Authorization；密钥被删或泄露就在控制台新建一把 |
402 | 积分不足 | 去充值 |
403 | 无权访问该资源（如查询他人任务） | 只查自己的任务 |
404 | 任务不存在或已过期 | 核对 task_id；任务有保留期 |
429 | 触发限流 | 退避后重试 |
5xx | 网关 / 上游异常 | 稍后重试；持续异常联系支持 |
常见问题
- 删除密钥后仍能调用几秒：删除会同步失效缓存、绝大多数情况即时生效；极端并发下可能有极短的缓存窗口。要彻底止血，删除后确认返回
401再放心。 - 任务失败要退款吗：超时等情况平台会退款；退款任务不会发 Webhook 回调，只能靠轮询确认。
- 结果图打不开：结果图 URL 完成后 24 小时过期，请在过期前转存到你自己的存储。