Idempotency keys

Idempotency keys are used in HTTP API requests to prevent the same request from being processed multiple times. It is used with POST requests, which are used to create new resources or perform an action.

For this reason, we implemented an HTTP Header called x-idempotency-key, this header is in UUID V4 format, which means that it is a universally unique identifier that is generated using a random number generator. This ensures that the x-idempotency-key is unique and cannot be duplicated accidentally.

When an API client makes a POST request with an x-idempotency-key header, the API checks to see if it has received a request with the same x-idempotency-key before. If it has, the API will return the same response as it did for the previous request with HTTP status 200, without creating a new resource. If it has not received a request with the same x-idempotency-key before, the API will process the request as normal and create a new resource.

The x-idempotency-key is stored by the API until it expires, which is typically 3 months after the request is made. After this range, the x-idempotency-key will no longer be stored and any subsequent requests with the same x-idempotency-key will be treated as new requests.

API clients can use the x-idempotency-key header to ensure that their POST requests are only processed once, even if the requests are made multiple times due to network issues or other problems. This can be particularly useful in situations where creating multiple copies of the same resource could cause problems, such as when creating Bank transfers or Collection links.