幂等

写端点必带 x-idempotency-key（UUID v4）。你的重试是必然的，

所以这一层是契约的一部分而不是可选优化。

四条语义

| 情形 | 行为 | HTTP |

|---|---|---|

| 同键 + 同 request body | 原样返回首次结果（含错误） | 首次的状态码 |

| 同键 + 异 request body | 拒绝 | 409 idempotency_key_reused |

| 首次请求仍在处理中 | 拒绝，稍后重试 | 409 idempotency_in_progress |

| 键不是合法 UUID | 拒绝 | 400 idempotency_key_invalid |

| 写端点缺这个头 | 拒绝 | 400 idempotency_key_required |

| 超过 24 小时 | 视为新请求 | 正常处理 |

「同键 + 同 body」返回的是首次那一次的结果，包括它是一次失败。

幂等的语义是「同一把键得到同一个结果」，不是「同一把键永远成功」。

504 与业务失败：处置相反

这两句必须写进你的重试逻辑，而不是留给值班的人临场判断：

• 收到 504 / 网络超时 → 用同一把键重试。我方可能已经处理完了，

换新键等于发起第二笔真实业务。

• 收到明确的业务失败（4xx 带 code）→ 改正后换新键重试。

同键会原样返回那次失败，你会以为「怎么改都没用」。

报价与出款的纪律相反

| 动作 | 幂等键 | 为什么 |

|---|---|---|

| 付款 / 出款重试 | 沿用同一把 | 拿回首次那笔，不产生第二笔付款 |

| 报价 | 每次换新 | 同键 24 小时内拿回第一份，而报价只活 75 秒 |

搞反的后果分别是「第二笔真实付款」和「拿着过期报价下单」。

我方这一侧的两个命名空间

你提交的键只活在开放 API 的幂等表里，主键带商户维度 ——

所以你和别的商户用同一个字符串当键不会互相影响。

资金层的凭证幂等键（账本、分发）一律由我方服务端生成，任何一个字符

都不来自你的入参。