AP
Idempotent Operations
Idempotency patterns for safe retries, duplicate prevention, and reliable state mutations
Details
Language / Topic
_UUniversal
Category
Architecture
Rules
balanced
- Make GET, PUT, DELETE, HEAD, and OPTIONS idempotent by design. POST and PATCH require explicit idempotency implementation.
- Require an Idempotency-Key header on all state-mutating POST endpoints. Store the key and return the cached response on replay.
- Use client-generated UUIDs as idempotency keys. Never use sequential or guessable identifiers.
- Return the same status code and response body for replayed requests — the client should not detect a difference between first and subsequent calls.
- Store idempotency records atomically with the business operation in a single transaction. Key + request hash + response + status must be saved together.
- Expire idempotency keys after a defined window (24-48 hours). Clearly document the retention window in your API reference.
- Return 409 Conflict if the same idempotency key is sent with a different request body — this prevents accidental key reuse across different operations.
- Implement PUT as full replacement (store exactly what the client sends). This makes PUT naturally idempotent.
- Design DELETE to return 200/204 on the first call and the same on subsequent calls (not 404). A delete of an already-deleted resource is still successful.
- Only cache successful (2xx) and conflict (409) responses for idempotency. Do not cache server errors (5xx) — the client should be able to retry.