Idempotent business commands
Count duplicate effects, not duplicate requests
Repeated requests are normal in a retrying system. The important measure is whether they create additional business actions or leave the caller without a reliable outcome.
In this article
Define the intended effect
For a booking command, the effect may be one booking with a stable identifier. For a notification command, it may be one accepted send operation under the downstream contract. Define the scope before choosing a metric.
A duplicate HTTP request is not necessarily a defect. It may be the expected response to a lost connection. Conversely, one inbound request can still create duplicate downstream work through an internal retry bug.
Correlate attempts using the account, operation and idempotency key, then connect them to actual target records or downstream operation identifiers.
Track the different outcomes
Measure matching retries that reused a result, conflicting key reuse, pending requests and uncertain effects. These categories explain whether the system is behaving as designed or struggling to establish an outcome.
Count duplicate business effects separately and inspect every observed case according to its consequence. A low overall rate can hide a serious defect in one command type.
Include missing effects too. A system that suppresses all retries by marking requests complete before execution can avoid duplicates while losing work.
Measure resolution time
Track how long callers remain in pending or uncertain states and how often operators must reconcile them. Idempotency is more useful when the original result can be recovered, not merely when additional attempts are rejected.
Break down uncertainty by downstream dependency and failure type. A missing status API, expired provider key or local crash may require different remedies.
Include the retry and retention window in reports. A result measured within a few minutes does not establish behaviour for an offline client replaying a request days later.
Verify with controlled faults
Use concurrent submissions, lost responses after commit and duplicate callbacks to exercise the contract. Compare the number of intended operations with final business effects.
Report sample sizes and interruption points, rather than claiming universal exactly-once behaviour from a small test. The guarantee should remain scoped to the implemented storage, downstream contract and retention period.
Acceptance is strongest when repeated attempts yield one correct effect and an explainable result, while conflicting reuse and unresolved cases remain visible. Request volume alone cannot establish that outcome.
Primary sources
AWS Builders' Library: idempotent APIsStripe: idempotent requestsReferences checked 11 September 2026.