# Idempotency

Safe retries with the Idempotency-Key header.

Send `Idempotency-Key` (8–255 characters `[A-Za-z0-9._:-]`, a UUID v4 is ideal) on POSTs; it is **required** on money-moving operations (payments, transfers, add money, exchanges, scheduled payments, mandates, collections, bulk payments, recipients, funds requests). Operations that require it show the **Idempotency-Key required** badge in the [reference](/reference).

- One key per logical operation; reuse the same key when you retry the same request.
- Same key + same body within 24 h: the stored response is returned with `Idempotency-Replayed: true`; nothing happens twice.
- Same key + different body: `422` [`idempotency-key-reused`](/errors#idempotency-key-reused). While the first request still runs: `409` [`idempotency-key-in-use`](/errors#idempotency-key-in-use) with `Retry-After`.
- `5xx` responses are not stored: retry with the same key.
- Responses that contain a one-time secret (`POST /api-keys`, `POST /integrator-webhooks`) are never replayed; do not retry those blindly: list and delete duplicates instead.

## Optimistic concurrency

Updates of versioned resources need `If-Match` with the `ETag` from your last read. A stale value is `412` [`precondition-failed`](/errors#precondition-failed); a missing header is `428` [`precondition-required`](/errors#precondition-required).