Handle timeouts and retries with clear idempotency rules to prevent accidental duplicate orders and other business transactions.
Who is this for? Development teams and process owners who want to reliably integrate writing API calls.
Use cases and context
A timeout does not say for sure whether an operation has failed. The server may have already saved the order, while the response is lost on the way back. If the same call is repeated without checking, duplicate orders, bookings, or notifications may occur.
In this context, idempotency means recognizing a repeated business request as the same process. To do this, the key, validity period and payload must match. A random new identifier every time it is repeated does not solve this problem.
The approach in detail
- Identify critical writes. For each operation, define how equality is detected and which changes constitute a new request.
- Link a stable operation identifier to a validated payload. Consider parallel calls, conflicts, and results that have already been saved.
- Test for error cases: lost response, slow server, double-click, and changed data under the same identifier. Provide a clear status retrieval or manual clearance path.
Expected outcomes
- Defined meaning of a repeated request
- Protection against unintentional duplicate actions
- Comprehensible status in case of unclear outcome
- Limited repetitions with documented error cases
Prepare for an informed decision
What is needed are API contracts, typical payloads, and the list of irreversible side effects. Distinguish secure reads from write business actions.
Logs should correlate operations, but not reveal secrets or full sensitive payloads. The retention of idempotency information should be matched with process runtime and data minimization.
Questions and answers
Is a client allowed to repeat automatically after each error?
No. Repeatability depends on the endpoint and the error. Without an agreed idempotence, a repetition can create a second business case.
What is expected with the same key and different data?
A clear conflict usually makes more sense than a silent overwriting. The exact treatment belongs in the interface contract.