错误与重试
诊断 HTTP 失败,并安全地从中断的提交中恢复。
错误响应
任务接口失败时返回 HTTP 错误状态码,以及包含字符串 code 和 message 的 JSON 对象。联系支持时请保留 X-Request-ID。
| HTTP | Code | 是否重试 | 处理方式 |
|---|---|---|---|
| 400 | invalid_params | 否 | 按模型输入要求修正请求。 |
| 401 | unauthorized | 否 | 检查或更换 API 密钥。 |
| 402 | insufficient_balance | 否 | 检查账户余额并充值。 |
| 403 | access_denied | 否 | 检查账户权限与模型权益。 |
| 404 | not_found | 否 | 检查任务 ID 与账户归属。 |
| 409 | conflict | 查看 reason | 若为 submission_pending,按 Retry-After 等待后查询原回执。其他情况检查请求体、报价或模型版本。 |
| 429 | concurrency_limit / rate_limit | 是,等待 Retry-After | 退避并等待可用容量。 |
| 500 | internal_error | 是,复用同一幂等键 | 保留诊断信息后重试。 |
| 503 | service_unavailable | 是,退避后重试 | 退避并检查服务可用性。 |
重试 recordInfo 永远安全。重试 createTask 前,请先阅读下面的幂等规则。
Retry-After 响应头与退避细节见。
恢复丢失的创建响应
保存首次请求的幂等键和请求体。响应丢失或收到 reason: submission_pending 时,用原 API Key 和 Idempotency-Key 调用 GET /api/v1/jobs/submission。待受理回执返回 HTTP 200,包含 status: pending 和 Retry-After。等待指定时间后查询同一回执。需要重放时,沿用原幂等键和完整请求体。其他回执状态及处理方式见。
如果你没有发送 Idempotency-Key,请不要重试任何响应丢失的 createTask。此时无法判断首次请求是否已经创建任务,盲目重试可能导致重复扣费。请记录每个返回的任务 ID,在确认之前把结果不明朗的提交视为「未知」。
生成失败
recordInfo 返回 HTTP 200 时,status 仍可能是 fail。此时查看其中的 error 对象。waiting 与 generating 表示任务仍在进行。确认失败的生成任务会释放预扣金额。
部分失败码属于上游状况,而非调用方错误:
| Code | 含义 |
|---|---|
generation_failed | 该输入无法生成结果。 |
no_provider | 提交时该模型没有可用渠道,稍后重试。 |
provider_out_of_credits | 平台未能连上上游渠道,与你的余额无关。 |
content_policy | 提示词或参考素材被拒绝,请调整输入。 |
provider_out_of_credits 和 no_provider 不是由账户余额引起的,不要因为这两个错误去充值。
可用性与参数支持情况请查看与。

