Idempotent Requests

The API provides support for idempotency, which ensures that you can safely retry requests without inadvertently performing the same action multiple times. When you're either creating or updating an object, you should include an idempotency key. This means that even if there's a connection issue and you have to resend the request, you won't end up with duplicate objects or updates.

To make an idempotent request, add the following header: Idempotency-Key: {key}.

Lithic's approach to idempotency involves storing the status code and body of the initial request associated with a specific idempotency key. This applies whether the request was successful or not. Any later requests using the same key will receive identical results, even if those results are 500 errors.

An idempotency key is a distinctive value, created by the client, that the server uses to identify repeated attempts of the same request. The method for generating unique keys is your choice, but we recommend using V4 UUIDs or any other random string with sufficient entropy to prevent overlaps. These keys can have a maximum length of 255 characters.

After a key is at least 24 hours old, it will be automatically deleted from the system. If such a key is reused post its deletion, a new request will be generated. To avoid misuse, the idempotency system will check the incoming parameters against those of the original request, and if they don't match, an error will be raised.

Only when an API endpoint begins its execution are the results saved. If there's a parameter validation failure or if the request clashes with another ongoing request, no idempotent outcome will be recorded since the API endpoint didn't start. You can safely resend such requests. To know more about when to safely resend idempotent requests, kindly refer to the provided link.

Note: Only POST requests recognize idempotency keys. Submitting idempotency keys with GET or DELETE requests is unnecessary and not recommended, as they're inherently idempotent.

Our client libraries automatically generate idempotency keys to be able to retry requests. You also have the option of providing your own custom idempotency keys.