HTTP 409 Conflict – Free, Online, Private

What HTTP 409 means

409 says the request is well formed and the server refuses it because of the current state. A version check failed, a unique key already exists, or an edit would overwrite a newer write. The body should describe the conflict well enough for the client to reconcile. 409 is not a generic duplicate of 400.

409 Conflict belongs to the 4xx client error class. Clients that only look at the class will group it with its neighbors. Clients that care about the exact code should use the narrower rule on this page, because the class is only the first digit.

When you see HTTP 409

When you see HTTP 409 Conflict, stop on that exact status line. 409 Conflict means the request collided with the current state of the resource. The trace that usually produces it: Two editors saved the same document and the second lost the version check. The 4xx client error class only tells you the first digit. A neighbor in that class is a different fault, and the fix on this page does not transfer to it.

Return 409 when a retry or a change by someone else makes the write invalid until the client refreshes. Send enough state for the client to merge. Use 412 when the failure is specifically a failed precondition header such as If-Match. Use 400 when the body is simply invalid.

How to fix HTTP 409

To fix HTTP 409, change the condition that made the server choose Conflict. Do not blind-retry. Fetch the current resource, reconcile, and write again. A blind retry can overwrite the other edit or fail the same way. Retry only after changing the request to match the current state. An immediate identical retry fails again. If the log line is a different code, leave this page. The mix-up people make with 409 is this one: 412 is a failed precondition header. 400 is a bad request. 423 is a WebDAV lock. 409 is a state conflict the client might resolve.

• A create used an id that already exists.
• A client retried a POST and the idempotency key mapped to a conflicting body.
• The server returned 409 with no current version, so the client could not rebase.

An access log that only stores 409 is not enough to tell these apart. Keep the method, the path, and a request id. Do not keep the Authorization header or a request body that might be a token. The status explains the outcome. It is not a place to echo secrets back to the client either.

Example response

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

{"error":"version mismatch","current":7}

The body names the current version. The client refetches or merges and sends version 7. A 409 that only says 'conflict' is legal and unhelpful. Include the state you are willing to reveal.

What the client should do

Do not blind-retry. Fetch the current resource, reconcile, and write again. A blind retry can overwrite the other edit or fail the same way.

Do not cache 409 as the resource. The conflict is about a write. The GET representation has its own cache entry.

Retry only after changing the request to match the current state. An immediate identical retry fails again.

Codes people confuse with HTTP 409

412 is a failed precondition header. 400 is a bad request. 423 is a WebDAV lock. 409 is a state conflict the client might resolve.