Conflict

Overview

409 Conflict means the request conflicts with the current state of the resource and cannot be processed. The request itself is well-formed, but it attempts a change incompatible with the server's present state.

Typical cases are an edit conflict (lost update) when two users modify the same document at once, a uniqueness constraint violated by an existing value, or a version mismatch.

When it happens

• It is returned when multiple clients try to update the same resource concurrently and one change would overwrite another.
• It occurs when inserting a duplicate into a field that must be unique — for example signing up with an already-registered email.

Request / Response example

PUT /api/docs/7 HTTP/1.1
Host: api.example.com
If-Match: "v3"
Content-Type: application/json

{"title":"Edited"}

HTTP/1.1 409 Conflict
Content-Type: application/json

{"error":"conflict","message":"Document was modified by another user","currentVersion":"v5"}

In code

app.put('/api/docs/:id', (req, res) => {
  const doc = db.get(req.params.id);
  if (req.headers['if-match'] !== doc.etag)
    return res.status(409).json({ error: 'conflict', currentVersion: doc.etag });
  // ...
});

@app.post('/api/users')
def create():
    if db.exists(email=request.json['email']):
        abort(409, 'email already registered')
    return {}, 201

Notes

• A validation failure on the field value itself (format, required) is better expressed with 422 Unprocessable Content than 409.
• A failing precondition header like If-Match relates to 412 Precondition Failed, so clearly divide their roles in your design.
• Including the current version or the point of conflict in the response body makes it easier for clients to implement auto-merge and retry.

Related status codes

Related headers

Specification