幂等与安全重试

Idempotency-Key 让 Gateway 识别对已有操作的重试。创建异步任务时必须提供，同步调用时可选。对可能需要恢复不确定结果的付费同步调用，建议始终提供。

发送前保存操作标识

为每个新的逻辑操作生成唯一值，在提交前持久保存，并放入请求头：

Idempotency-Key: <your-saved-operation-key>

重试时保持相同的 Key、HTTP 方法、路径、查询参数和请求体。Key 在组织、项目与逻辑方法及路径范围内标识操作。用相同 Key 提交不同输入或查询参数会返回 HTTP 409。

仍在进行的操作也可能返回 409。请检查稳定错误码，按产品规定的轮询或恢复流程处理；不要把每个冲突都理解为输入变化。

重试保留什么

操作	保证
付费操作	沿用原操作及其冻结的价格版本。
创建异步任务	重复提交返回原任务标识。
同步调用	保留已记录的资金结果，但不保证重放原始响应正文。

新 Key 表示新的操作，可能产生新的费用，不能用它恢复之前操作的标识。

超时后恢复

超时或客户端断开不能证明执行尚未开始。如果异步提交的响应丢失，使用已保存的 Key 和完全相同的输入重试提交。拿到任务 ID 后，通过产品提供的免费读取端点查询进度与结果。

同步调用也应使用原 Key，以保留资金结果。不要为了恢复丢失的响应正文，悄悄创建另一个付费操作。

退避重试

响应包含 Retry-After 时遵循该值，并逐步增加重试间隔。Gateway 可以在内部重试安全的幂等读取，但不会自动重试写请求。应用只能在保留原操作标识且符合端点文档行为时重试写请求。

各状态对应的处理方式见错误与恢复。WHOIS 批量指南展示完整的异步提交、轮询、分页和取消流程。