# Idempotency

Retry a POST after a network failure without creating duplicates by sending Idempotency-Key, and learn when you get the stored response back and when you get a conflict.


When a POST gets no answer (a timeout, a dropped connection), you cannot tell whether the server ran it. If the request carries an `Idempotency-Key` header, you can send it again with the same key: the server runs it once and answers every retry with the response it stored.

## Where it applies

The header is honoured on every `POST` to the Business API (`$BUSINESS_API`) and the Consumer API (`$CONSUMER_API`), for creates and for actions on an existing record alike. `GET`, `PATCH`, `PUT` and `DELETE` requests ignore it. Without the header the request runs as usual, with no protection against retries.

## Key rules

- 1 to 255 visible ASCII characters, no spaces. A UUID v4 that your system generates once per logical operation works well.
- A key outside that format is refused with `400`, and `invalid_params` names `Idempotency-Key`.
- A key is bound to the credential (`Authorization`), the context (`X-Context-ID`), the method and the path. The same key sent with a different API key or to a different path counts as new.
- The stored response stays available for 24 hours after the first request.

## Example request and response

This request creates a customer and needs the `business:customers:create` scope.

```bash
curl -sS -X POST "$BUSINESS_API/customers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: 9b2f4c1e-7a3d-4e8b-b5c6-0d1e2f3a4b5c" \
  -H "Content-Type: application/json" \
  -d '{"customer_type":"individual","category":"residential","display_name":"Felismina Mabunda","phone":"+258849876543"}'
```

First response, `201 Created`:

```json
{
  "id": "cus_2kGa3TnW7qLzE5rHbV1mXc8yJdP",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "customer_type": "individual",
  "category": "residential",
  "display_name": "Felismina Mabunda",
  "phone": "+258849876543",
  "status": "active",
  "created_at": "2026-11-19T10:42:07.318250Z",
  "updated_at": "2026-11-19T10:42:07.318250Z"
}
```

Send the identical request again and you get `201` with the same `id`, plus two headers: `Idempotency-Key` echoing your key and `Idempotent-Replayed: true`, which tells you this is the stored answer and not a second run.

## Conflict: same key, different body

The server compares each retry's body with the first request's body. Change a single field and reuse the key, and you get `409`:

```json
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "Idempotency-Key was already used with a different request payload.",
  "instance": "$BUSINESS_API/customers",
  "code": "CONFLICT",
  "error_code": "request.idempotency_conflict",
  "request_id": "req_4f1c9a2b7e3d48a6b0c5d2e1f9a8b7c6"
}
```

Generate a fresh key whenever the request content changes. The `type` field links to the site's error page when the operator has configured one; otherwise it is `about:blank`.

## What gets stored

- Responses with a status below 500 are stored, `4xx` refusals included. If the first attempt failed on an invalid field, a retry with the same key returns the same refusal: fix the body and use a new key.
- `5xx` errors are not stored. Retry with the same key and the request runs again.
- Request bodies larger than 4 MiB bypass idempotency protection.
- Keys live in the memory of the server instance that answered. A retry handled by another instance, or after a restart, runs again.
- A few endpoints also record the key in the database. The cashier shift commands keep it for 7 days, so a retry there is recognised after a restart too; the operation's entry in the reference describes it.

## Next steps

- [Read the API error codes](/docs/getting-started/errors)
- [Receive payments and confirm them by webhook](/docs/guides/receive-payments)
- [Create customers from another system](/docs/guides/import-customers)

