Idempotent API Operations Template

GET, PUT, and DELETE are naturally idempotent by HTTP specification. GET is read-only. PUT replaces the entire resource, so repeating it produces the same state. DELETE on a specific resource is safe to retry (it returns 404 or 204 on subsequent calls). POST is the main method that needs explicit idempotency keys because each POST is intended to create a new resource or trigger a new side effect.

Match the TTL to the longest realistic retry window for your consumers. For synchronous user-facing operations, 24 hours is standard. For batch processing systems that might retry hours later, 48-72 hours may be appropriate. For [webhook](/glossary/api-first-design) delivery retries that span days, consider 7 days. Shorter TTLs save storage but risk treating delayed retries as new requests.

Return a 422 error explaining that the key was already used with different parameters. This prevents a subtle class of bugs where the client reuses a key by accident (for example, using a session ID instead of a per-request UUID). The server detects the mismatch by comparing a hash of the stored request body against a hash of the current request body.

Use a cache (Redis) for high-throughput, low-latency scenarios where losing records on a cache restart is acceptable (the worst case is a duplicate operation). Use your primary database when the cost of duplication is severe (financial transactions) and you need durability guarantees. Some teams use a hybrid: cache for fast lookups, database for durable writes, with the cache populated from the database on misses.

Each service should manage its own idempotency records. The client sends one key to the entry-point service, which stores it. If that service calls downstream services, it generates new idempotency keys for each downstream call, derived from the original key (e.g., `{original_key}:{downstream_service}`). This ensures that retrying the entry-point request also retries downstream calls safely without creating duplicates in any service. ---