Idempotent Request Design
You'll learn how to structure HTTP requests so they can be safely retried multiple times without creating duplicate side effects or corrupting data.
What Is Idempotency?
In web development, an idempotent request is one that produces the same result no matter how many times you execute it. Think of it like pressing an elevator button: whether you press it once or ten times, the elevator still comes to your floor exactly once. The extra presses don't summon additional elevators.
When implementing retry logic (like you learned with exponential backoff), you need to ensure your requests won't cause problems if they're executed multiple times. A failed payment that gets retried shouldn't charge the customer twice. A "create user" request that times out shouldn't create duplicate accounts.
Designing Idempotent Requests
Some HTTP methods are naturally idempotent:
- GET: Reading data multiple times doesn't change anything
- PUT: Replacing a resource with specific data yields the same result each time
- DELETE: Deleting something that's already gone is still "deleted"
The tricky method is POST, typically used for creating resources or triggering actions. To make POST idempotent, include an idempotency key—a unique identifier the client generates and sends with the request. The server remembers this key and recognizes retries:
POST /api/payments
Headers:
Idempotency-Key: unique-client-generated-uuid-123
Body:
{ amount: 50, currency: "USD" }
If this request fails and retries with the same key, the server recognizes it and returns the original result without processing it again.
When to Use Idempotency Keys
Use idempotency keys for any operation with important side effects: payments, order creation, data mutations, or external API calls. Generate the key on the client before the first attempt, and reuse it for all retries of that specific operation.
Key Takeaway: Design requests to be idempotent—especially POST operations—by using unique idempotency keys, allowing safe retries without duplicate side effects or data corruption.