LEARN. PRACTICE. GROW.Concept and mechanism
Two teams may change the same resource from different earlier reads. A validator such as an ETag suitable for strong comparison allows conditioning a write on the observed version. If the condition fails, the consumer needs current state and a decision about reconciling intent rather than removing protection and silently overwriting. PATCH describes a partial modification whose meaning depends on media type. JSON Patch contains ordered operations including test; a number and the corresponding numeric text are not equivalent values in that test. Patch-document atomicity does not create an automatic transaction across every service involved in the business.
Guided application
In a fictional scenario, the client loses the response after sending a creation request. Timeout leaves the outcome unknown: the server may have completed it. Before retrying, use the idempotency contract or query an existing operation reference. An idempotency key works only if the server defines storage, scope, concurrency, and retention. Stripe documentation is a provider-contract example rather than a universal rule for any API. Changing the key on every attempt may turn retry into a new operation. Retain the same intent and payload when required by the contract; after retention expires, reconcile the outcome before assuming protection.
A lost response does not mean an unexecuted operation; a retry must preserve intent identity.
Common pitfalls
Timeout as failure without effects; new key on every retry; PATCH always idempotent; dropping If-Match to resolve conflict.
Related topics: API resources and contracts · Requests and outcomes · Authorization and boundaries
Control write concurrency and request repetition separately.
Reference: Idempotent requests · HTTP semantics RFC9110; OpenAPI3.2.1; selected primary standards and provider contracts consulted2026-09-30