Response deduping recognizes repeated requests for the same operation and prevents their effects from being applied more than once. It makes retries safe when a non-idempotent request may have succeeded even though its response never reached the client. section 26.0 section 26.1
Implement the pattern with a request identifier and a cached result:
- Have the client generate a unique identifier for each operation that must be serviced once. section 26.2
- Store the identifier when the API first processes the request, together with a fingerprint of the request content. section 26.6
- Cache the original response and return that same response when the identifier is retried. section 26.2
- Choose expiration and invalidation rules deliberately, and apply the mechanism first to methods where duplicate work is costly. section 26.4 section 26.6
Retrying a resource creation
A client sends a request to create a resource with request ID req-123. The server creates the resource, but the response is lost. The client retries req-123; the server detects the duplicate and returns the cached creation response, including the resource's unique ID, without creating another resource. section 26.2 section 23.3.7
A cached retry response may be stale because other clients can update the resource afterward. That staleness is intentional: the retry should reproduce the result of the original request, not report a later state. Without the special identifier, retrying large imports can create duplicate resources when transactions are unavailable or impractical. section 26.3.3 section 23.3.7
Listing 23.7 Some sample JSON resources with import request IDs for deduplication
{ importRequestId: "abc", sender: "users/1", content: "hi" } #1
{ importRequestId: "def", sender: "users/2", content: "hi back" }
Sample resource payloads show importRequestId values carried alongside resource data for deduplication. section 23.3.7
