幂等请求

关于以幂等方式处理重试的最佳实践。

API 支持幂等请求，允许安全地重试请求而不会意外地执行相同的操作两次。当发起幂等请求时，如果 API 请求中出现错误（如超时或连接丢失），您可以安全地重试请求，而不会有创建第二个资源或执行两次更新的风险。

幂等性的工作原理是为给定的幂等键存储第一个响应的状态码和正文，无论请求成功还是失败。使用相同幂等键的后续请求将返回相同的响应。

幂等键是由您生成的唯一键，API 使用它来识别同一请求的后续重试。我们建议使用 V4 UUID，或其他具有足够熵以避免冲突的随机字符串。幂等键最长可达 255 个字符，有效期为 24 小时，之后幂等键可以重新用于另一个请求。

只有在 API 开始执行时，幂等请求的响应才会被保存。如果您的请求验证失败或与同时执行的另一个请求冲突，则不会保存响应。重试这些请求是安全的。

目前，只有 POST /transactions 端点支持幂等请求。

发起幂等请求

要发起幂等请求，请在请求中指定 Idempotency-Key 标头。

curl -i -X POST "https://api.efundpay.com/v4/transactions" \
    -H "Authorization: Bearer [JWT]" \
    -H "Idempotency-Key: bffa9ce6-7a8a-449c-889a-65bd2ee86903" \
    -d "{...}"

我们的大多数 SDK 都支持在 POST transactions 调用中传递此标头。

并发请求

当使用与之前请求相同的 Idempotency-Key 发起幂等请求，且原始请求仍在处理中时，您将收到错误。您可以安全地重试此请求。我们建议在重试交易时应用指数退避。

{
  "type": "error",
  "code": "concurrent_request",
  "status": 409,
  "message": "A request with this idempotency key is still being processed. Retry later.",
  "details": []
}

冲突请求

当使用与之前请求相同的 Idempotency-Key 发起幂等请求，但请求不同时（例如，请求正文不同），您将收到错误。重试此请求不会改变错误响应。您应该检查您的请求。

{
  "type": "error",
  "code": "bad_request",
  "status": 400,
  "message": "Idempotency key already in use.",
  "details": []
}