Idempotency keys help prevent duplicate transactions by ensuring that identical requests are processed only once. When you include an idempotency key in your request headers:
  • If you make a request with the same idempotency key and identical request body as a previous request, you’ll receive the same response as the original request, but the request will be processed only once.
  • If you make a request with the same idempotency key but a different request body, you’ll receive a 409 Conflict error.
This is particularly useful for retry scenarios where you want to ensure that a transaction isn’t processed multiple times due to network issues or other temporary failures. Requests that move money have idempotency keys as optional request headers. Here’s how they work:
RequestHeaders
{
    ...
    "Idempotency-Key": "8c9accbb-b9e9-49af-91f4-ef2ba3a9cf04"
}
Best practices for idempotency keys:
  • Use a unique value for each unique transaction
  • Generate keys that are long enough to avoid collisions
  • Consider using UUIDs or other unique identifiers