# 处理错误

错误响应的格式，以及哪些错误可以原样重试。

接口用 HTTP 状态码表示结果，出错时响应体里有机器可读的错误码。按错误码写处理逻辑，不要解析说明文字。

## 错误格式

错误响应包含 `error` 对象和 `trace_id`：

| 字段 | 说明 |
| --- | --- |
| `error.code` | 机器可读的错误码，按它处理错误。 |
| `error.message` | 供人阅读的说明，可能调整，不要拿来判断。 |
| `error.details` | 可选的结构化详情，例如余额不足时所需的预留金额。 |
| `trace_id` | 排查问题用的追踪标识，联系我们时请提供。 |

## 能否重试

| 情况 | 怎么做 |
| --- | --- |
| `400`、`401`、`403`、`404` | 请求本身有问题，原样重试还会失败。按错误码修正后再发送。 |
| `409` | 多数是幂等键冲突，见「[幂等与重试](./api-docs-zh-idempotency.md#conflict)」；`asset_not_ready` 等素材可用后用同一个键重试。 |
| `429` | 频率、余额或额度受限。有 `Retry-After` 时等这么多秒，再用同一个键重试；余额不足先充值。 |
| `500`、`503` | 结果不确定。用原请求体和同一个 `Idempotency-Key` 重试，不会重复创建或扣费。 |
| 超时、连接断开 | 同上，用同一个键原样重试。 |

每个错误码的含义、处理办法和是否收费见「[错误码](./api-docs-zh-api-errors.md)」。

## 细节字段

- `unsupported_capability`：`error.details` 列出不能同时满足的能力和相关的请求参数名，按参数调整请求。
- `insufficient_balance`：`error.details` 给出这次请求所需的预留金额和价格版本。

## 任务失败

接口接受请求后，任务仍可能在后台失败。失败的任务 `status` 为 `failed`，`error.code` 给出原因，例如 `input_fetch_failed` 或 `generation_failed`，全部取值见「[状态与原因](./api-docs-zh-api-statuses.md#task-error)」。失败的任务结算后不收费。

## 下一步

- [错误码](./api-docs-zh-api-errors.md)：每个 error.code 的含义、状态码和出现的接口。
- [幂等与重试](./api-docs-zh-idempotency.md)：用同一个 Idempotency-Key 重试，不会重复创建任务，也不会重复扣费。