# 错误与重试

## 错误响应

任务接口失败时返回 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` 响应头与退避细节见[速率限制与并发](/docs/rate-limits)。

## 恢复丢失的创建响应

保存首次请求的幂等键和请求体。响应丢失或收到 `reason: submission_pending` 时，用原 API Key 和 `Idempotency-Key` 调用 `GET /api/v1/jobs/submission`。待受理回执返回 HTTP 200，包含 `status: pending` 和 `Retry-After`。等待指定时间后查询同一回执。需要重放时，沿用原幂等键和完整请求体。其他回执状态及处理方式见[媒体报价与任务恢复](/docs/media-workflow)。

如果你没有发送 `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` **不是**由账户余额引起的，不要因为这两个错误去充值。

可用性与参数支持情况请查看[服务状态](/status)与[模型文档](/docs/models)。