Deduplicate API requests for safe request retry.

Idempotency of API requests is defined as the ability to execute the same operation multiple times without changing the result beyond the first try. It is a design principle to overcome the inherent unreliability of networks, and provide robustness around critical operations in the event of failure.

Idempotency of GET requests

The Smartpay API guarantees the idempotency of GET requests, so you can always safely retry them. Because of the inherent unreliability of the network, a certain amount of failure can be expected. In many of these cases, the server-side success of the operation is ambiguous from the perspective of the client, and the client doesn't know whether retrying the operation is safe. A connection terminating midway during a refund request is an example of this. Because of this, clients need a way of reconciling failed requests with the server, and idempotency provides a mechanism for that.

Idempotency for other requests

Including an idempotency key guarantees that POST, PUT and PATCH requests are idempotent, and instructs the API to do all the work required to deduplicate operations. This way, clients can safely retry request which include an idempotency key, as long as the retried requests happen within 6 hours from when the key was first received by Smartpay's servers. This way, for example, if a request to create a refund doesn't respond because of a network connection error, the client can retry the request with the same idempotency key as the original request to guarantee that no more than one refund is created.

Making idempotent requests

Idempotency keys are sent in the Idempotency-Key: <key> header of the request. This key value should be generated by the client and sufficiently unique so the server can unambiguously recognize subsequent retries of the same request within the 6 hour window. You can identify a previously executed response that's being replayed from the server by the Idempotency-Replay header which is set to true

Idempotency key uniqueness and collision

How you create unique keys is up to you, but we suggest random strings with enough entropy (e.g. V4 UUIDs) to avoid collisions. For retries, the Smartpay idempotency layer compares incoming request parameters with those of the original request linked to the original idempotency key, and will raise a collision if these don't match. In case of a collision, the Smartpay API will return a 422 Unprocessable Entity response.