幂等性

​

如何发送

curl -X POST …/v1/payouts \
  -d '{ "idempotency_key": "payroll-2026-07-001", … }'

curl -X POST …/v1/payouts \
  -H "Idempotency-Key: payroll-2026-07-001" \
  -d '{ … }'

​

重试时会发生什么

• 不会创建新操作，资金也不会再次变动。
• 您会收到 200 OK（而非 201/202），返回原始对象并附带 idempotency_hit: true。

{
  "payout_id": "same-as-the-first-time",
  "status": "processing",
  "idempotency_hit": true
}

​

该用哪个键重试？

​

建议

• 使用来自您自己系统的标识符（订单 ID、工资单 ID 等），而不是 时间戳或每次重试都重新生成的 UUID。
• 在调用 API 之前先持久化该键；这样在超时后即可重试，且保证不会 产生重复。
• 遇到网络错误或 5xx 时，用相同的键重试。遇到校验类 4xx 时， 修正请求并使用新的键。