Idempotency Key Collision

Overview

What does Idempotency Key Collision mean?

An idempotency key collision occurs when two independently intended operations receive the same idempotency key within a scope where the service expects that key to be unique.

How it works in practice

A key collision occurs when two logically different operations receive the same idempotency identifier within the key's uniqueness scope. A payment API should bind a key to the authenticated merchant, endpoint or operation type, normalized request details and retention period. If a second request reuses the key with materially different parameters, the safe response is a conflict rather than quietly returning an unrelated result or executing a new payment. Systems must choose high-entropy keys and define what happens after the retention window expires.

Limits and common misunderstandings

A merchant could mistakenly reuse 'checkout-1' for every order. Without tenant isolation, two merchants might interfere with each other's requests. Hashing the payload alone does not distinguish two intentionally separate equal-amount payouts.

Additional implementation considerations

Collision-handling should be tested with concurrent requests, reused keys across merchants, changed payloads and retries long after a timeout. A clear conflict response helps the client repair its identifier logic without guessing whether money moved. A provider may legitimately return the first result for the same key and same parameters; different parameters should instead be rejected within the retention scope. Logging must avoid exposing confidential request payloads.

Related glossary terms

Duplicate API Request; Payment Retry; Idempotent Payment Operation