错误与重试
只重试暂时性故障；请求错误应先修正再发送。
调用失败时，先保存 HTTP 状态、脱敏错误正文、调用时间、端点、Model ID 和可用的请求标识，再决定是否重试。
常见错误
| 表现 | 优先检查 | 是否直接重试 |
|---|---|---|
400 参数错误 | JSON、Model ID、字段类型和模型支持 | 否，先修正请求 |
401 鉴权失败 | API Key、Bearer 格式和凭证状态 | 否，先修正凭证 |
403 访问受限 | 账号、模型范围、地区或来源限制 | 否，先确认权限 |
404 路径或资源不存在 | API 地址、端点、Model ID 或任务标识 | 否，先核对配置 |
429 请求过多 | 请求频率、并发和返回的限流提示 | 降低速率后有限重试 |
5xx 服务异常 | Request ID 和原请求是否已执行 | 根据错误有限重试 |
| 超时或连接中断 | 网络、客户端超时和请求状态 | 不要盲目重发 |
| 余额或预算不足 | 可用余额、Key 预算和费用保护 | 先解决限制 |
实际错误正文和状态码以 API 返回为准。
设置重试
只重试可能恢复的错误，并设置最大次数和总等待时间。优先使用响应中明确提供的重试提示。
示例：最多重试 3 次，等待约 1 秒、2 秒、4 秒，并增加少量随机延迟。这是应用侧策略示例，不表示平台限制一定会在对应时间解除。不要同时在 SDK、业务代码和网关开启无上限重试。
避免重复请求
客户端超时后，先到 Requests 检查原请求状态。生成图片或长耗时任务时，如果已经取得请求或任务标识，应先查询现有状态。只有接口明确支持幂等机制时，才使用对应字段或请求头。
联系支持
提供 Request ID、调用时间与时区、Model ID、端点、HTTP 状态、脱敏错误以及已经执行的排查步骤。不要发送密码、验证码、完整 API Key 或无关的敏感内容。