Idempotency key

Definition

An idempotency key is a client-supplied identifier attached to an API request that allows the receiver to recognise and safely deduplicate retries of the same logical operation. When a network failure or timeout makes the outcome of an earlier request uncertain, the client can retry with the same key. The receiver — usually a payment, ledger, or transaction system — uses the key to determine whether the operation has already been performed; if it has, the original result is returned instead of the operation being executed again. The key is typically a UUID or another high-entropy string and is stored alongside the response for a defined retention window.

Idempotency keys are mandatory at every write boundary in XVICA-built transaction systems. The ledger refuses writes that arrive without a key; duplicate keys return the original outcome rather than executing again; key state is observable in the same way regular events are. Retention windows are sized against the upstream's longest plausible retry window, with explicit policy for what happens at the boundary. Because retries are the network's normal mode of operation, idempotency is treated as a correctness property of the platform, not as a feature.