幂等性

可变的 API 操作需要 Idempotency-Key 请求头，以确保在网络重试的情况下操作不会被重复执行。

为什么使用幂等性？

在分布式系统中，请求可能因各种原因（超时、连接中断）在服务器已处理操作后失败。通过使用相同的 Idempotency-Key 重复请求，服务器会将其识别为重复请求，并返回原始操作的结果，而不会再次执行。

需要幂等性的端点

Idempotency-Key 请求头在所有 POST、PUT 和 PATCH 方法上是必需的，包括：

• PIX Out 转账
• 动态 QR Code 生成
• 退款请求

工作原理

1. 首次请求：客户端发送带有唯一 Idempotency-Key 的请求（建议使用 UUID v4）。服务器处理操作并存储结果。
2. 后续请求（相同密钥）：
   • 如果请求体相同，服务器返回之前存储的结果（HTTP 200/201/202）。
   • 如果请求体不同，服务器返回冲突错误（HTTP 409 idempotency_conflict）。

过期时间

幂等性密钥的存储期限为 24 小时。超过此期限后，密钥将过期，使用相同密钥的新请求将被视为全新操作。

最佳实践

• 密钥生成：使用通用唯一标识符（UUID）。请勿尝试在不同类型的操作之间复用密钥。
• 重试：对网络错误（5xx）实现指数退避重试策略，始终保持相同的 Idempotency-Key。
• 处理 409：如果收到 409 idempotency_conflict，请检查您是否正在使用已用于其他用途的密钥发送不同的操作。