API Idempotency and Retry Guide

Safe retries, duplicate POST requests, idempotency keys, timeout recovery and backoff. Last updated August 31, 2026.

MDN explains that an HTTP method is idempotent when repeating the same request has the same intended server effect as sending it once. Safe methods are idempotent, and PUT and DELETE are idempotent by method semantics, while POST and PATCH are not guaranteed to be. See MDN Idempotent and MDN HTTP request methods. Real APIs still need careful retry design because payment, order, email and job endpoints often use POST.

Retry decision table

Situation	Retry?	Required evidence
GET timeout	Usually safe	Request URL, query, status if any, timeout point.
PUT timeout	Often safe when route follows HTTP semantics	Resource ID, complete replacement body, server idempotency behavior.
DELETE timeout	Often safe but response may differ	Resource ID and whether delete is soft, hard or queued.
POST timeout	Only safe with explicit idempotency behavior	Idempotency key, unique business key or duplicate detection.
429 or 503	Retry with delay	`Retry-After`, rate-limit headers and backoff policy.

Idempotency key pattern

curl -i -X POST https://api.example.com/orders \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-create-20260831-0001" \
  --data '{"customerId":"cus_123","cartId":"cart_456"}'

An idempotency key should represent one logical operation, not one network attempt. A retry should reuse the same key; a new customer action should use a new key.

Server-side checklist

Store the idempotency key with the normalized request body hash.
Return the original result when the same key and same request body are retried.
Reject or flag the same key with a different request body.
Choose a retention window that covers real client retries and job retries.
Log request ID, idempotency key, user or tenant and final resource ID.

Backoff policy template

attempt 1: immediate
attempt 2: wait 1s + jitter
attempt 3: wait 2s + jitter
attempt 4: wait 4s + jitter
attempt 5: stop and surface a recoverable error

retry only on: timeout, 429, 502, 503, 504
do not retry blindly on: 400, 401, 403, 404, 409, 422

Incident note

operation:
method:
endpoint:
idempotency key:
request id:
timeout or status:
retry count:
resource created:
duplicate detected:
client fix:
server fix:

The most dangerous retry bug is a silent duplicate side effect. Design POST retries as a business workflow, not merely a network loop.