Many of Elements' API endpoints support idempotency through the use of a special Idempotency-Key header. Idempotency allows for safely retrying requests without the risk of accidentally performing the same operation multiple times.
For instance, if a request to create a payment failed due to transient network errors, it can be retried with the same idempotency key to guarantee that no duplicated payments were created.
An idempotency key is a unique value by which the server uses to identify duplicated requests. They are usually automatically generated by our clients, and we recommend using V4 UUIDs should you choose to generate these yourself.
Elements guarantee idempotency by saving the status code and body of the API response from the first request that finished execution. And this includes successful (200) API responses as well as failed API responses (400s, as well as 500s). Note that the response is saved only if a request has began execution. If the request failed before it starts execution, for example due to authentication errors, failed parameters validation, or conflict with another concurrently executing request, then no response is saved and it is safe to retry them later.
Since idempotency is not meant to be a permanent archive of historic requests, idempotency keys are expired and purged from the system after 72 hours.
Note that the incoming parameters of an idempotent request is also recorded and compared to those of the original request. If any consistency was discovered then the system responds with an idempotency error to avoid misuse.