API retry caused duplicate operation
Verdict
When retrying an API request results in duplicate operations, this is usually not a client-side bug, but a boundary mismatch between retry behavior and the API’s execution guarantees.
If the API does not provide strict idempotency at the operation level, retries shift risk from failure to duplication. At that point, continuing to retry is a choice, not a requirement.
Why This Happens
Retries assume one of two conditions:
- The previous attempt definitively failed, or
- The system guarantees idempotent execution
Across system boundaries, neither is reliably true.
Common structural reasons include:
- The initial request succeeded server-side but the response was lost or delayed
- The API acknowledges receipt before completing execution
- Idempotency is scoped narrowly (e.g. per key, per window, or per state)
- Internal retries or queues replay the same operation independently
From the client’s perspective, the retry “fixes” a timeout. From the system’s perspective, it creates a second valid instruction.
The resulting duplication is a systemic effect, not an implementation mistake.
Where You Can Stop
Once duplication is observed or plausibly triggered, you can usually stop:
- Automatic retries for accepted or timed-out requests
- Assuming retries are always safer than failures
- Adding more retry layers to compensate for uncertainty
- Treating duplication as evidence of faulty client logic
Beyond this point, additional retries increase risk rather than reliability.
Meaningful progress requires explicit execution guarantees, not persistence.
What This Page Is Not
This page does not:
- Recommend retry strategies
- Define idempotency keys or mechanisms
- Solve duplication after it occurs
Its role is to mark the boundary where retries stop being protective and start becoming a liability.
Retries reduce failure rates only when execution boundaries are explicit. Without them, retries merely move the failure elsewhere.