Idempotency Key

Overview

Idempotency Key is a client-generated unique value that lets a server recognize repeated submissions as the same logical operation. It is used to prevent retries from creating duplicate payments, payouts, orders, or other side effects. It differs from a request ID, which may identify an attempt without guaranteeing duplicate suppression.

A typical implementation works as follows: The client creates a key for one business command, sends it with the request, and reuses it only when retrying that same command; the server stores and returns the original outcome.

Common risks include reusing one key for different payloads and expiring records too early. Important failure modes include reusing one key for different payloads, expiring records too early, inconsistent scope, and retrying without a key. These failures can create conflicts or duplicates.

Core controls require teams to bind keys to actor, endpoint, and payload hash, define retention, return deterministic conflicts, store outcomes durably, and test concurrent retries. Configuration changes to Idempotency Key should be versioned and tested under burst, timeout, dependency failure, and restart conditions.

Operational evidence should include idempotency key, payload fingerprint, first request time, response reference, status, and expiration. Idempotency Key should be documented alongside Retry Policy, API Call, and Duplicate API Request. The Idempotency Key policy should define which failures are retryable, how long the decision remains valid, and how duplicate effects are prevented.

For Idempotency Key, a missing response should remain uncertain until status lookup or reconciliation confirms whether the original operation executed. The Idempotency Key implementation should bound attempts, preserve the original operation identity, and stop before retries amplify a dependency failure.