Idempotency

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. When creating or updating an object, use an idempotency key. Then, if an error occurs, you can safely repeat the request without risk of duplicating the processing effort or performing the update twice.

To perform an idempotent request, provide an additional Idempotency-Key Header element to the request.

cURL

curl --request POST \
     --url https://client.gainsystems.com/api/v1/customers \
     --header 'content-type: application/json' \
     --header 'Idempotency-Key: 943ut39gbfw39gf2' \

Idempotency is applicable to data creation and update endpoints. GET requests or endpoints that trigger delete tasks are not applicable.

The client generates an idempotency key, which is a unique key that we use to recognize subsequent retries of the same request. Idempotency keys can be generated specific to your requirements, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys are up to 255 characters long.

We save results only after an endpoint starts executing. If incoming parameters fail validation or if the request conflicts with another concurrent request, we don't save the idempotent result because the API endpoint never begins execution. You can retry these requests. In other words, if the API does not accept the payload initially, the idempotency key is not used or considered.

Key Validity Period

Idempotency keys are valid for a period of 24 hours. This means that if you use the same idempotency key within this 24-hour window, any duplicate requests will be recognized and handled as such, preventing unintended side effects. However, using the same key after 24 hours will be treated as a new, valid request. By way of example:

Suppose you make a POST request to create a new vendor with an idempotency key 1234 at 10:00 AM on May 1st. If you accidentally send the same request with the same key 1234 again at 2:00 PM on May 1st, the API will recognize this as a duplicate and will not accept the record.

However, if you use the same idempotency key 1234 at 11:00 AM on May 2nd, the API will treat this as a new request and will process it accordingly, potentially creating a new record. This is because more than 24 hours have passed since the original request.