跳转到主要内容

​
为什么需要

超时或不确定的 5xx 后常会重试。若没有幂等键，服务端可能把每次重试当成新请求 — 产生重复任务、多扣积分或重复 Webhook。 X-Idempotency-Key 标识同一次业务提交。在同一 API Key 下，相同路径 + Key 在 TTL 内（默认 24 小时）只接受一次。相同意图的重试用同一个 Key；新任务用新 Key。
幂等防的是同一次提交的重复投递，不是禁止发起两次不同的任务。

​
怎么用

对 Open API 的每一个 POST 请求（/openapi/v1/**）都加上该请求头：
规则：
  • 去空格后非空，最长 64 字符
  • 在第一次请求前生成 Key，并随本次尝试保存，便于安全重试
  • 不要用同一 Key 提交不同内容的请求 — 会返回 409 Conflict

​
Key 已被占用时

  • HTTP 409 Conflict
  • 响应头 Retry-After: 2
  • 响应体：code: 409，message 含 Idempotency key already used

​
安全重试 vs 新任务

​
示例

若结果不确定，用同一个 Key 重试。不要在每次重试时换新 Key，否则可能重复写入。