Safe HTTP retries and idempotency
A network timeout does not prove that the server did nothing. Retrying a state-changing request without verification can execute it twice.
Key points in one minute
- Automatically retry only operations known to be idempotent.
- Paid actions need a stable idempotency key and a post-check.
- Retry policy is defined separately for every endpoint.
- One idempotency key cannot be reused with different parameters.
Method semantics
RFC method semantics define safe and idempotent properties, but actual retry safety also depends on the API contract and resource implementation.
Maintain an endpoint catalog with effect, retryPolicy, and reconciliationMethod fields. GET must not secretly trigger state changes; treat POST as unsafe for automatic retry by default. PUT and DELETE may be idempotent by intent, but clients still need to consider payments, webhooks, and API-specific contractual limits.
Unknown outcome
If a response is lost after command submission, store an outcome_unknown state and first query the actual object, payment, or command status.
An outcome_unknown state should block only a competing operation on the same object. The worker queries the order, payment, or equipment by stable identifier and compares expected fields. If the provider offers no reliable post-check, route the task to manual reconciliation and prohibit automatic external-command replay.
Idempotency key
One user intent gets one stable key. The server stores the outcome and returns it on retries without creating a second effect.
Generate the key once on the client and store it with the user's intent: type, object, amount, and quantity. The server should atomically claim the key before side effects and return the previous result on replay. A page refresh must not create a new key unless the user confirms a separate operation.
Retrying after 429
Even a safe request should be retried with delay and an attempt limit. For unsafe requests, first prove the original was not applied.
Metrics should show retry count, idempotency-key cache hits, outcome_unknown volume, reconciliation time, and manual decisions. Alert when one key appears with different parameters because it indicates a client conflict or attack. Return a safe error without exposing the original operation to another user.
Practical checklist
- 1Classify every command by side effect.
- 2Add an idempotency key.
- 3Support outcome_unknown and manual reconciliation.
- 4Create an effect and reconciliation-method catalog.
- 5Alert on parameter conflicts for one key.
Sources and documentation
This material is based on primary, official, and technical sources. The article is an original summary written for this knowledge base.