Preparing your workspace
Idempotent operations can be repeated without producing unintended additional effects, while idempotency keys can protect non-idempotent operations from duplicate processing.
Networks are not perfectly reliable. A client may send a request, fail to receive the response, and retry the same operation. For actions such as payments, registrations, or resource creation, blindly processing retries can create duplicates. APIs can use idempotency keys, unique constraints, or carefully designed operations to make retries safe. Idempotency should be designed around the business operation, not added as a generic label.
A payment creation endpoint can accept an idempotency key so a network retry does not create two payment records.
POST /api/payments
Idempotency-Key: payment-order-123
Content-Type: application/json
{
"orderId": "order-123",
"amount": 999
}The server can recognize a repeated request using the same idempotency key and avoid processing the same operation twice.