To retry identical requests with the same effect without accidentally performing the same operation more than needed, you can add the Idempotency-Key header to your requests. This is useful when API calls are disrupted or you did not receive a response. In other words, retrying identical requests with our idempotency key will not have any side effects. We will return the same response for any identical request that includes the same idempotency key.
If your request failed to reach our servers, no idempotent result is saved because no API endpoint processed your request. In such cases, you can simply retry your operation safely. Idempotency keys remain stored for 60 minutes. After 60 minutes have passed, sending the same request together with the previous idempotency key will create a new operation.
Please note that the idempotency key has to be unique for each request and has to be defined by yourself. We recommend assigning a random value as your idempotency key and using UUID v4.
Idempotency is only available for POST requests and was implemented according to the Idempotency HTTP Header Field Working Document.
| Scenario | Condition | Expectation |
|---|---|---|
| First time request. | The idempotency key has not been seen during the past 60 minutes. | The request is processed normally. |
| Repeated request. | The request was retried after the first time request was completed. | The response from the first time request will be returned. |
| Repeated request. | The request was retried before the first time request was completed. | 409 conflict. It is recommended that clients time their retries using an exponential backoff algorithm. |
| Repeated request. | The request body is different than the one from the first time request. | 422 unprocessable entity. |
Example
curl --request POST \
--url https://api.sandbox.datatrans.com/v1/tokenizations/220112095131012129 \
--header 'Authorization: Basic MTEwMDAxNzc4OTpNQUd6UUVEbkVxd001d0Vr' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: e75d621b-0e56-4b71-b889-1acec3e9d870'