HTTP If-Match helps a client make an operation conditional on the resource still matching a known representation. It is useful when several users or processes can update the same record. Without a concurrency check, one client can unknowingly overwrite a change made after it last read the data.
The header is part of a broader application design. A safe implementation needs an appropriate entity tag, an atomic check-and-update operation, and a user-facing way to resolve a failed precondition. This guide explains those requirements without treating a concurrency token as authentication or authorization.
Understand the problem HTTP If-Match addresses
Imagine two users reading the same profile configuration. One updates a notification setting while the other edits a display label from an older copy. If the second request replaces the whole record without checking its version, it can erase the first user’s change.
This is a lost-update problem, not necessarily an invalid request. Each user may have permission and submit well-formed data. The missing information is whether the update is based on the current resource state.
Define which endpoints need optimistic concurrency. Whole-record replacement, configuration editing, and important administrative changes are common candidates, but the correct policy depends on the application’s update semantics.
Return a meaningful entity tag
An ETag identifies a representation under the server’s design. For concurrency control, ensure that a relevant resource change produces a different tag and that the server applies the intended comparison semantics. A constant or poorly maintained tag cannot detect conflicting changes.
If-Match uses strong comparison. A weak tag with the W/ prefix does not satisfy that comparison in the way a strong validator does. Do not assume any string displayed as an ETag is suitable for the operation.
Record how tags relate to representations, content negotiation, and application state. Different encodings or views can complicate a simplistic design. Choose a consistent contract that both clients and the server understand.
Send the precondition with the update
A client reads the resource and retains the relevant tag, then includes it with the supported modification request. A simplified header example is:
If-Match: "resource-version-7"The value is illustrative, not a recommendation for a fixed production tag. The server must determine whether the submitted validator matches the resource under its current rules before applying the requested change.
Keep the tag with the data it describes. A client that accidentally associates an old tag with a different object can create confusing failures. The resource identifier, user context, and update body still need validation.
Make the check and modification atomic
A server that reads the version, checks it, and later writes without coordination can still lose a race. Another update may occur between the check and the write. Use the database or storage system’s appropriate conditional operation or transaction model.
For example, an application can use a version condition as part of the database update and inspect whether the intended row was changed. The exact implementation depends on the database and resource model. Do not assume a header parser alone solves concurrent writes.
Test competing requests that use the same initial tag. The expected result should preserve the configured concurrency rule rather than allow both operations to overwrite each other silently.
Handle a failed precondition clearly
When the condition does not match, the operation should follow the documented failure path, commonly HTTP 412 Precondition Failed for If-Match. The MDN If-Match reference explains the comparison and response semantics.
Give clients a safe way to refresh the current resource and present the conflict. A user may need to review the newer state, reapply selected edits, or abandon the old update. Do not blindly resend the entire outdated object with a fresh tag.
Distinguish a concurrency conflict from an authorization failure or validation error. Clear error categories help clients recover without guessing or weakening the precondition.
Define missing-precondition policy
Decide whether the endpoint accepts updates without a precondition or requires one. If old clients can omit the check indefinitely, they can undermine the intended protection. Document the compatibility plan and enforce the selected policy consistently.
Do not replace a missing tag with a convenient current value server-side. That changes the request from based on known state to unconditional from the client’s perspective. The server should not invent the evidence that the client reviewed the latest representation.
Review wildcard behavior separately when it is supported by the operation. An existence condition is not the same as requiring the specific version the user read.
Keep permissions and validation independent
An ETag is not a secret credential and should not be used as the only authorization control. Authenticate the caller, verify access to the object, and validate the proposed values before executing an allowed update.
A user who knows a current tag still must not modify another account’s record. Our API object-level authorization guide explains this separate boundary.
Review sensitive information in error responses. A conflict message should not expose the complete current private object to a caller who is not permitted to read it.
Test clients, retries, and partial updates
Include tests for current tags, stale tags, weak tags, missing headers, and simultaneous modifications. Confirm that rejected requests leave the resource unchanged and do not trigger external side effects before the conditional update succeeds.
Consider retry behavior after a network timeout. The client may not know whether its first operation completed. Combine concurrency checks with idempotency or another supported recovery design when repeated business actions would be harmful.
Partial updates can reduce accidental replacement of unrelated fields, but they do not automatically eliminate all concurrency problems. Decide which changes can safely combine and which still require a version precondition.
Frequently asked questions
Does If-Match authenticate a user?
No. It expresses a condition about a resource representation. Identity, authorization, and input validation remain separate server-side requirements.
Can I use a weak ETag for this check?
If-Match uses strong comparison, so a weak validator does not satisfy the same match. Use the semantics documented for your endpoint and server implementation.
What should a client do after a conflict?
Refresh the permitted current state and resolve the difference deliberately. Avoid silently retrying an old replacement body as if the newer changes did not exist.
