Idempotency Record

Overview

Meaning and scope

An Idempotency Record is the server-side record that binds an idempotency key to an operation, request identity, processing state, and reusable result. It allows repeated requests to return the established outcome instead of executing the operation again. It is different from a general request log because it participates directly in concurrency control and response selection for duplicate attempts.

Mechanism and operation

Operational review of Idempotency Record should separate successful recovery from repeated attempts that only increase latency or load. In production, teams should define ownership and apply atomic creation, request fingerprint, processing status, response or error reference, expiration time, tenant scope, and conflict detection. A Idempotency Record decision should use documented method semantics and provider error classes rather than message text alone. Useful measures include record creation conflicts, cache hit rate, in-progress age, record recovery count, and duplicate execution count. Manual intervention for Idempotency Record should begin only after automated status checks cannot determine a safe final outcome.

Practical payment example

A payout request ID is stored with its outcome so a repeated instruction returns the previous result instead of sending funds again.

Operational checks

Configuration changes to Idempotency Record should be versioned and tested under burst, timeout, dependency failure, and restart conditions. The Idempotency Record policy should define which failures are retryable, how long the decision remains valid, and how duplicate effects are prevented. For Idempotency Record, a missing response should remain uncertain until status lookup or reconciliation confirms whether the original operation executed.

Distinctions and limits

The main risks include concurrent duplicate execution, incomplete records after crashes, replay of the wrong result, stale in-progress states, and unauthorized cross-tenant lookup.

Related reading

Related definitions: Idempotency Store, Idempotency Result Cache.