The labs on this site need JavaScript to run. The same content is written out below.
Learn › Networking › HTTP
Retries and idempotency
No response came back, so the request was sent again
On a network, a request or a response can be lost, and when no response arrives, the client sends the same request again. Depending on the HTTP method, running a request several times either gives the same result (the method is idempotent) or it does not.
Checked against documentation and standards · Checked against the HTTP standard (RFC 9110)
Concepts in this lab
- Safe methods and idempotent methods
- Safe methods are read-only methods that do not change the state of the server: GET, HEAD, OPTIONS, and TRACE. Idempotent methods are methods for which sending the same request several times has the same effect on the server as sending it once: all the safe methods plus PUT and DELETE. POST and PATCH are not guaranteed to be idempotent, so sending one twice can cause it to be processed twice. This is the basis for deciding whether a request may be sent again when no response arrives.
- HTTP methods
- The part of an HTTP request that indicates the action the request wants to perform on a resource. GET means read, POST means create or a processing request, PUT means replace the whole resource, PATCH means modify part of it, and DELETE means delete. Use each one according to its meaning so that HTTP behavior such as caching and retries works as expected.
- Idempotency and idempotency keys
- Idempotency is the property that performing the same request several times gives the same result as performing it once. A network problem can cause the same request to be sent again, so operations that must not be duplicated, such as payments, must be made idempotent. An idempotency key is a unique value that the client attaches to each request. When a request arrives with a key that the server has already processed, the server does not process it again and returns the earlier result.
- HTTP status codes
- A three-digit number that shows the result of the server's handling of a request. 2xx means success, 3xx means a move to another location (redirection), 4xx means a problem with the client's request, and 5xx means an error on the server side. Common ones are 200 (success), 201 (created), 400 (bad request), 401 (authentication required), 403 (no permission), 404 (not found), and 500 (server error).
Try these
- Default settings — The response to the POST is lost once. Two orders are created.
- PUT in the same situation — Even when it runs twice, the result is the same as running it once.
- Sending DELETE again — The response code of the second request is different, but the state of the server is the same.
- A PATCH that increases a value — The quantity goes up once for every retry.
- Adding an idempotency key to the POST — The server recognizes the repeated request and handles it only once.
- When the request is lost — The server never handled it, so retrying causes no problem.
Running with the default settings
- This is the initial server state. Order 1 (mouse, quantity 2) exists.
- First request: The server handled the request (201 Created (order 2)). But the response was lost on its way back. The client cannot tell whether the server handled the request, so it sends the same request again.
- Retry #1: The server handles the request and returns the response 201 Created (order 3). This time the response reached the client.
Result of this run
- POST is not idempotent. Every execution creates a new order, so the same order was created 2 times. This is the typical way duplicate processing happens in payments and orders.
Code
POST /orders HTTP/1.1
Content-Type: application/json
{ "item": "keyboard", "quantity": 2 }
// Client: if no response arrives within 3 seconds,
// send the same request again, unchanged
Assumptions of this model
The definition of idempotency follows the HTTP standard (RFC 9110). A method is idempotent if the intended effect on the server of sending the same request several times is the same as that of sending it once, and GET, HEAD, OPTIONS, and TRACE (the safe methods) and PUT and DELETE belong here. The standard does not guarantee that POST and PATCH are idempotent (a PATCH can be designed to be idempotent, depending on its content). The Idempotency-Key header is a convention widely used in payment APIs and similar services, and it has not been finalized as a standard.
Previous lab: HTTP caching and ETag · Next lab: Redirection