> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yingtu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误处理与安全重试

> 处理参数、认证、限流和异步提交结果不明确的情况，避免重复生成图片。

| 响应或状态              | 含义               | 客户端处理                         |
| ------------------ | ---------------- | ----------------------------- |
| HTTP `400`         | 模型、字段、图片数据或参数值无效 | 修正请求，不要原样重试。                  |
| HTTP `401`         | API Key 缺失或无效    | 检查或轮换密钥。                      |
| HTTP `403` 且提示余额不足 | 凭证有效，但账户无法支付本次请求 | 补充余额或改用有余额的开发凭证，不要原样重试。       |
| 查询任务返回 HTTP `404`  | 任务不存在，或不属于当前账号   | 核对任务 ID 和凭证。                  |
| HTTP `429`         | 达到请求或账号限制        | 如果存在 `Retry-After`，按其等待并逐步退避。 |
| 临时 `5xx`           | 请求暂时无法完成         | 使用有上限的指数退避和随机抖动重试。            |
| 任务状态为 `failed`     | 后台生成失败           | 读取 `error.message`，再判断是否新建任务。 |

参数校验和身份验证失败不应自动重试。

模型与尺寸不匹配也属于参数错误：2.5 模型应省略 `imageSize`，Lite 不能发送 2K 或 4K。

<Info>
  如果异步提交在返回 `task_id` 前发生网络超时，结果是不明确的：任务可能已经创建。
  当前接口没有客户端幂等键，应限制自动重试次数，避免产生重复的计费任务。
</Info>

同步请求遇到可重试的上游错误时，服务端可能在健康渠道之间切换，而客户端侧仍是一笔请求。
异步任务不会在执行结果未知时盲目重新生成；任务明确进入 `failed` 后，已预扣费用会退回。