Skip to navigation
Yoco API

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:

Retry with the same keyResponse
Same body, first request returned a stored responseThe status code and body of the first response, with an Idempotent-Replayed header set to true
Same body, first request still in progressHTTP 409 with code conflict. Retry after a short delay with the same key.
Same body, first request returned an error that isn’t storedThe request runs again. The endpoint’s API reference describes any result it recovers from a first attempt that succeeded.
Different body, first request still in progress or its response storedHTTP 400 with code validation, and the error names the Idempotency-Key header. Send a new key for a different request.
Any body, the API can’t check the keyHTTP 503 with code service_unavailable. Retry later with the same key.

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:

{
"type": "https://developer.yoco.com/docs/api/error-codes/validation",
"title": "Validation Error",
"detail": "The request contains one or more validation errors.",
"status": 400,
"code": "validation",
"errors": [
{
"detail": "The idempotency key was already used with a different request body. Send a new key for a different request.",
"parameter": "Idempotency-Key",
"code": "validation"
}
]
}

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.