幂等与重试
在同一作用域内,相同请求使用相同 Idempotency-Key 时,会返回已保存的结果。作用域按已认证用户 / api_key_id,或服务端签发的 anonymous_client_id 区分,不只按 IP 区分。请求尚在处理中时,并发请求会排队处理,或返回处理中状态及 Retry-After。
- 必须提供 Idempotency-Key 请求头(最大长度为 256)
- 有效期为 24 小时;相同键值 + 相同请求体 → 返回已保存的结果
- 并发请求尚在处理中 → IDEMPOTENCY_IN_PROGRESS + Retry-After
- 匿名作用域:服务端签发的 X-Duan-Client-Id / anonymous_client_id 与 Idempotency-Key 共同确定,不只按 IP 区分。浏览器也可使用 duan_anon。