幂等

所有会修改状态的 POST、PUT、PATCH、DELETE 都必须带 Idempotency-Key，除非该操作虽使用 POST 但被明确标记为只读（目前是签署预览和 waiver 解析）。key 必须为 1–64 位 A-Za-z0-9._-。

预留记录按 (workspace, partner-v1, key) 唯一，因此轮换或更换凭据不能让同一逻辑请求执行两次。请求哈希覆盖方法、完整 URL/查询串和解析后 body 的稳定序列化。

状态	结果
首次占用	handler 获得预留
已完成且请求相同	重放已存状态/body，并返回 Idempotent-Replayed: true
同 key、不同请求	409 idempotency_key_reused
相同未完成预留不足五分钟	409 idempotency_key_in_progress
未完成至少五分钟，或持久化结果不确定	409 idempotency_outcome_unknown

这是失败关闭的防重复措施，不是 exactly-once 保证。预留在校验/处理之前建立，不会自动释放或接管。只有已完成结果在 24 小时重放窗口后可被清理。完成操作使用已确认的 compare-and-set；结果不确定时不会返回 handler body。

遇到 idempotency_outcome_unknown，必须假设业务写入可能已提交并停止重试。不要改 key、凭据、URL 或 payload 绕过预留。先对账，再携带服务端 request_id 联系支持；绝不要发送 secret 或认证材料。