错误、幂等与安全重试

保持一次逻辑操作不变

付费创建接口要求 8–200 字符的 Idempotency-Key。生成一次后，与完整请求一起保存；超时或断线重试时复用两者。

同一键与同一规范化请求会返回原操作；同一键换了请求内容则冲突。原请求仍在接受过程中时，可能返回可重试的“处理中”冲突。幂等记录至少保留 24 小时，不要假设永久去重。

去重范围包含账户、操作和 API Key 身份（MCP 对应 OAuth 客户端）。更换 API Key 后，即使幂等字符串相同，也可能创建新任务。创建结果不明时，应先找回已知任务 ID，再处理凭据轮换。

创建结果不明确时，应先找回原任务，不能悄悄换新键。确实要重新生成或修改请求时，应重新获得批准，并使用新逻辑键。

读取错误结构

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "param": null,
    "retryable": true,
    "request_id": "example-request-id",
    "details": {}
  }
}

这是结构示意，不承诺错误消息文本完全相同。根据 HTTP 状态和 error.code 分支处理，检查 retryable，保留 request_id 供支持排查。不要记录原始请求头、图片正文、提示词或签名 URL。

如何处理

无权访问资源时，服务可能有意返回“未找到”。不要尝试枚举他人的资源 ID。

给重试设定边界

遵循 Retry-After（秒数或 HTTP 日期）；缺失时使用带随机抖动的指数退避。设置最大尝试次数和总体截止时间。停止本地等待，不代表服务端已接受的任务也停止。

读取操作可在临时传输故障后重试。付费创建结果不明确时，只有已保存幂等键且请求不变，才能重试。不要盲目重试没有幂等保护的上传或其他非幂等操作。

达到截止时间后，保存已知任务 ID，稍后恢复。任务终态失败时，先检查部分产物，再决定重新导出还是重新生成。

账户限额与排查

PROVIDER_CONTENT_REJECTED 目前覆盖 Seedance 明确内容审核拒绝的终态，不属于应原样自动重试的临时错误。读取任务的 credits.status、credits.refunded 和 credits.released；credits.charged 已是净扣费，不要再减一次退分。确认审核拒绝且尚无产物、导出未开始时，一键任务返还原流程整笔积分。客户端超时或导出失败不等同于这一条件，退分也不构成新一轮付费生成的授权。

通过 GET /account 获取当前限制；响应中的限流头可能反映当前计数窗口。多建 Key 不会增加账户容量。多个任务的轮询应分散执行，避免所有客户端同时突发请求。

向支持提供公共请求 ID、已知任务 ID、时间、错误码和简短描述。移除凭据和私有输入。不完整结果见轮询与下载，有界重试实现见 Python 示例。