Idempotency Conflict

Overview

An idempotency conflict occurs when an idempotency key already associated with one request is reused for a request whose operation or parameters are materially different. This is not an ordinary duplicate: a legitimate retry repeats the same logical request. Rather than returning the earlier result for a different instruction, it rejects the request with a conflict that tells the client to investigate or use a new key.

The service retrieves the stored request fingerprint and compares it with the new payload, endpoint, account, and operation scope. In operational terms, this flow should remain connected to API Security , because its upstream decision and downstream outcome must be interpreted together. The comparison policy should define which fields are material, how payloads are canonicalized, how keys are scoped, and what response is returned. These records support Payment Retry and let an operator reproduce the result from authoritative evidence rather than relying on a dashboard snapshot or a provider’s latest status alone.

Idempotency Conflict should remain distinct from Payment Retry and Duplicate Request, because each can represent a different stage, record, control, or financial outcome. Silently accepting the changed request can execute an unintended action or return a misleading result.

Rejecting harmless representational differences, however, can create unnecessary failures unless canonicalization is consistent. The final control should feed Duplicate Request , preserve the original evidence, and document any correction, override, or manual action.

Logs must not expose sensitive data but should contain enough identifiers to diagnose client bugs. Controls should preserve original payloads, correlation and causation identifiers, delivery attempts, validation results, consumer acknowledgements, and any replay or dead-letter action.