Idempotency

Overview

Idempotency means repeating the same logical operation produces no additional intended effect beyond the result of processing it once. Idempotency does not make every operation reversible or safe to retry; the server must implement durable duplicate detection and clients must reuse the same key for the same intent. Idempotency is the property that repeating an equivalent operation under its defined key and scope does not create additional unintended effects. Clients must reuse the same key only for the same intent. Clients need bounded exponential backoff, jitter, retry limits, a deadline, and status lookup before assuming that a timed-out operation never executed. Manual intervention for Idempotency should begin only after automated status checks cannot determine a safe final outcome.

Assertions should verify final provider and business state, not only an HTTP status or locally mocked response. Idempotency must define the protected operation, client-supplied or derived key, uniqueness scope, request-equivalence rule, retention window, stored result, retry behavior, and conflict response. Systems should define key scope, retention, response replay, conflict behavior, and recovery after partial processing. A client supplies or derives a stable logical operation identity, and the server recognizes repeated submissions so it can return the existing result rather than create another payment, order, or payout. Idempotency makes retries safe when networks or responses fail. For Idempotency, a missing response should remain uncertain until status lookup or reconciliation confirms whether the original operation executed. A Idempotency decision should use documented method semantics and provider error classes rather than message text alone.

Simultaneous duplicates must be claimed atomically, and reuse of one key with different parameters should be rejected.