Idempotency is a key concept in Fintech and Payments which ensures that a request made to a server can be repeated multiple times without causing unintended side effects. It is particularly important because it helps prevent duplicate or erroneous transactions, which can result in incorrect balances, overcharges, or undercharges.
In order to make a POST request Idempotent, include the X-Idempotency-Key in the request headers. The value of X-Idempotency-Key must be unique, we recommend using a V4 UUIDs (32 characters), or another random string with enough entropy to avoid collisions.
GET and DELETE requests are Idempotent by default.
How Idempotency Ensures Reliable API Operations
This section provides information about idempotency in API requests. Idempotency allows you to safely repeat a request without causing unintended side effects. It ensures that the result of an operation remains the same, regardless of how many times it is performed.
Idempotency Key
- Each request with a unique X-Idempotency-Key will be treated as a new request.
- If a request is idempotent, the X-Idempotency-Key will be included in the response headers.
- Keys are automatically removed from the system after 8 days, and reusing a pruned key will generate a new request.
Request Handling
- When a request with the same X-Idempotency-Key is sent:
- If the request body is identical to the original, the system will return the same response without reprocessing the request. In addition, the response headers will include two additional keys:
X-Cached-Request-Id and X-Cached-Request-Time - If the request body is altered, the system will throw an error indicating that the request cannot be processed with the same X-Idempotency-Key.
- In case of an error (4XX or 5XX), retrying with the same X-Idempotency-Key is allowed.
- If the request body is identical to the original, the system will return the same response without reprocessing the request. In addition, the response headers will include two additional keys:
Key Usage
- The same X-Idempotency-Key can be used for different endpoints.
Concurrent Requests
- If multiple requests with the same X-Idempotency-Key are received simultaneously:
- The first request will be fulfilled, and subsequent requests will return the same response as the first request.
- If the first request is still being processed, the other requests will return an error message indicating that the request is still in process.
It is recommended to include the X-Idempotency-Key in your API requests to ensure idempotent behavior and to handle request retries effectively.