> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.yoco.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.yoco.com/_mcp/server.

## 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](/docs/api/error-codes/validation),
and the error names the `Idempotency-Key` header.

> **Info**
>
> 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 key                                                | Response                                                                                                                                                     |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Same body, first request returned a stored response                    | The status code and body of the first response, with an `Idempotent-Replayed` header set to `true`                                                           |
| Same body, first request still in progress                             | HTTP 409 with code [conflict](/docs/api/error-codes/conflict). Retry after a short delay with the same key.                                                  |
| Same body, first request returned an error that isn't stored           | The 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 stored | HTTP 400 with code [validation](/docs/api/error-codes/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 key                                  | HTTP 503 with code [service_unavailable](/docs/api/error-codes/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](https://developer.yoco.com/api-reference/yoco-api/orders/create-order-v-1-orders-post). 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:

```json
{
  "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](/docs/api/error-codes/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.

> **Warning**
>
> 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.