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#