Idempotency
What’s idempotency?
An API call is idempotent if it produces the same outcome however many times it’s made. A network error or a timeout can leave you unsure whether a request reached Yoco. An idempotent request lets you retry it without the risk of performing the operation twice.
Sending an idempotency key
To make a request idempotent, send a unique string in the optional Idempotency-Key header. A key is 1 to 255
printable ASCII characters. Use a UUIDv4 to avoid accidental collisions.
A key outside these limits returns an HTTP 400 status code with code validation,
and the error names the Idempotency-Key header.
An endpoint that accepts the Idempotency-Key header lists it among its request headers in the API reference.
Retrying a request
When you retry a request with the same key, the response depends on the body you send and on the outcome of the first request:
The API reference for each endpoint that accepts the key lists the first responses it stores, for example creating an order. After a timeout, a network error or an error that isn’t stored, retry with the same key. To send a changed request after a stored error, use a new key.
Idempotent-Replayed: true marks a response to a retry that the API didn’t process again: the stored first response,
or a result the endpoint recovered from an earlier attempt. A retry can also return the result of the first
request without the header.
A retry with a different body returns:
A retry while the first request is still in progress returns the conflict body,
with the detail “A request with the same idempotency key is already being processed.”
Key scope and expiry
A key belongs to the business on the access token, to the app that sends it and to the endpoint it’s sent to. Another business, another app connected to the same business, or another endpoint, can use the same key without affecting it. Two apps that send the same key to the same business get separate results.
A stored response is kept for 24 hours. The key is freed when those 24 hours end, or when the first request returns an error that isn’t stored. A request with a freed key runs again and the API doesn’t compare its body with the first request. The endpoint’s API reference describes any earlier result it returns instead.
Don’t reuse a key for a different request. The API compares the body only while the first request is in progress or its response is stored.