验证码 API 如何避免重试产生重复任务

超时后复用相同 Idempotency-Key 和请求体，处理幂等冲突，并在重放窗口之外保存 taskId。

适用于授权自动化测试、风控 QA 与浏览器集成。请仅在有权测试的站点和业务流程中使用。

一个业务任务对应一个固定键

POST 前先保存 Idempotency-Key，长度为 8–128 字节。重试时，键必须与完全相同的请求体绑定。不要在重试循环里生成新的 UUID。

超时可能掩盖已成功创建的任务

服务端接受请求但响应丢失时，换新键重发可能产生另一笔计费任务。应重放原键与原请求体，取得 taskId 后保存，并改用 GET 查询。

business operation -> persist key + exact JSON
POST -> network outcome unknown -> retry same key + same JSON
POST -> taskId available -> persist taskId -> GET only

HTTP 409 怎么处理？

IDEMPOTENCY_CONFLICT 表示该键已用于冲突的请求。重试前对比原始类型与参数。不同业务任务应使用独立键；但更换键不能作为绕过原任务结果不明的办法。

taskId 的保存应超过重放窗口

任务幂等记录约保留 25 小时。长期查询与业务去重应在自己的记录中保存 taskId，不能假设旧 POST 永远可重放。如果从未取得 taskId 且窗口已过，先核对原请求结果，再决定是否重建。

哪些故障可重试？

网络故障与可重试 5xx 可在有限预算内使用原键与请求体重试。限流时遵守 Retry-After。字段错误与权限问题要先修正，不应重复发送坏请求。参见错误处理与 API 参考。

Python 和 Node.js 示例从环境变量读取已保存的键，并支持用 taskId 恢复查询。