Skip to main content

​
Overview

Network issues, timeouts, or service interruptions can make it unclear whether an API request succeeded. Idempotency keys address this by allowing you to safely retry requests without creating duplicate operations. When you include an idempotency key, you can retry the same request as needed. If the original request was successful, the API returns the same response. If it was not, the request is processed normally.

​
Idempotent Requests

To make an idempotent request, include an Idempotency-Key header with a unique value: 
curl --request POST \
     --url https://api.sandbox.lead.bank/v1/ach \
     --header 'Idempotency-Key: example-payment-123-retry-001' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "echo": "Hello!"
     }'

​
Idempotency Key Requirements

  • Key format: Use any string up to 255 characters. We recommend using a V4 UUID or another random string to ensure uniqueness.
  • Key expiration: The idempotency key is valid for 48 hours from the time of API submission. After this period, the key expires and can be reused for another API request.

​
How It Works

When you make requests with idempotency keys, our API handles them as follows:
  • Same key, successful original request: The API returns the identical response from the original request without performing any new operations.
  • Same key, failed original request: Depending on the error, the API may attempt the operation again. Please look at the response for further details.
  • Same key, different parameters: The API returns an error since the request parameters don’t match the original.
Two requests are considered identical when they use the same idempotency key and target the same endpoint within the 48-hour window.

​
Why Use An Idempotency Key?

  • Eliminates duplicate operations: Network issues and timeouts won’t result in duplicate payments, transfers, or other critical operations.
  • Simplifies error handling: You can safely retry any request without complex logic to check if the original succeeded.
  • Improved reliability: Guarantees that repeated requests will not have additional unintended effects, giving you confidence in the consistency of your transactions.