Idempotency
What is idempotency?
An API call or operation is idempotent if it always produces the same outcome, regardless of how many times it is executed. This ensures that accidental duplicate calls do not cause unintended consequences.
The idempotency key is a unique string created by the client and is used by the server to recognise subsequent retries of the same request.
Idempotent requests using our API
Yoco enables idempotency by allowing API operations to include an idempotency key, which is a unique string. This key acts as a safeguard against accidental duplicate calls that could lead to undesired outcomes.
important
This feature is especially valuable when an API call fails due to network issues or the temporary unavailability of Yoco's services.
The method for creating unique idempotency keys is flexible, but we recommend using UUIDs or other randomly generated strings.
Idempotency works by saving the resulting status code and body of the first request made for any given idempotency key,
regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, status code
and a response header of Idempotent-Replayed set to true.
Keys are removed from the system automatically after 24 hours. A subsequent request with the same key after its expiry period, will be treated as a new request.
To execute an idempotent request, include an additional element called Idempotency-Key in the request headers.
- cURL
important
All POST requests accept idempotency keys.
Sending idempotency keys in GET and DELETE requests has no effect and should be avoided, as these requests are idempotent by definition.