The response can get lost
Consider a request to create an order: the server may complete it while the client never receives the response. If the client repeats the request, the outcome depends on the API contract. That ambiguity belongs in the initial design of an operation with business effects.
Define a repetition contract
One possible design asks the client to supply a stable idempotency key for the same intent. The server must define the key’s scope, expiry and behaviour when reused with different content. Storing a key without coordinating it with the business outcome leaves race conditions unresolved.
Limit additional work
Retries can worsen an overload. AWS guidance recommends limiting attempts and using increasing delays; jitter adds variation so that clients do not all retry together. The policy needs to distinguish transient failures from errors that repetition cannot resolve.
Make the budget visible
For a specific workflow, document the total time budget, which layer retries and how many attempts it permits. Inspect client and SDK policies too. Independent retries across multiple layers can generate much more traffic than expected.
Test the awkward case
Include a test where the server commits the operation but its response is lost. Then send two concurrent attempts with the same key and verify the business outcome. Add metrics for retries, detected duplicates and budget exhaustion to observe production behaviour.