409 Conflict

This is an educational reference page about HTTP 409 Conflict. The page itself is served as 200 OK so it can be indexed as HTTP documentation.

The request conflicts with the current state of the target resource. The client may be able to resolve the conflict and resubmit.

Specification

Registered in the IANA HTTP Status Code Registry as Conflict. Defined in RFC 9110, Section 15.5.10.

What it means

HTTP 409 Conflict means the request could not be completed because it conflicts with the current state of the resource. RFC 9110 expects the user to be able to fix the conflict and try again, so the server SHOULD explain the conflict in the response body.

When to use it

Return 409 when an update is based on an old version of the resource and someone else changed it first.
Return 409 when creating a resource that would duplicate a unique value, such as a username or slug that is already taken.
Return 409 for state-machine violations, such as cancelling an order that already shipped.
Use 412 instead when the client sent If-Match or If-Unmodified-Since and the precondition failed.

Common causes

Two clients edited the same record, and the slower one sent its update based on stale data.
A unique constraint, such as an email address or slug, already has that value.
The resource is in a state that does not allow the action, such as an archived project.

How to fix it

Fetch the current resource, merge or redo the change, and resubmit.
Show the user which value conflicts and let them choose another.
For concurrent edits, have clients send If-Match with the ETag they last saw so conflicts are caught before data is overwritten.

Examples

Version conflict on update

PUT /api/docs/17 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "version": 4,
  "title": "Q3 plan",
  "body": "..."
}

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

{
  "type": "https://api.example.com/problems/version-conflict",
  "title": "Document was changed by someone else",
  "status": 409,
  "detail": "You sent version 4, but the current version is 5.",
  "currentVersion": 5
}

Duplicate unique value

POST /api/teams HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "slug": "design"
}

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

{
  "error": "slug_taken",
  "detail": "A team with slug 'design' already exists.",
  "existing": "/api/teams/design"
}

Common mistakes

Returning 409 with no explanation. RFC 9110 says the body should help the user recognize the source of the conflict.
Using 409 for validation errors that have nothing to do with current state, such as a malformed email. That is 400 or 422.
Retrying 409 automatically without changing the request. It will conflict again.

Developer notes

APIs disagree on duplicates: some return 409 Conflict, others 422 Unprocessable Content. 409 fits when the request clashes with data that already exists, and 422 fits when the input breaks a rule on its own. Pick one per API and document it.

Questions

What does HTTP 409 Conflict mean?

HTTP 409 means the request conflicts with the current state of the resource, such as an edit based on an old version or a duplicate unique value.

Should a duplicate email return 409 or 422?

Both are common. 409 says the request clashes with an existing record. 422 treats it as a field validation error. Choose one and use it consistently.

What is the difference between 409 and 412?

412 means a precondition header such as If-Match evaluated to false. 409 means the server detected the conflict some other way, such as a version field in the body.

Header and content rules

What RFC 9110 says about a 409 response, quoted from the RFC. The 4xx class rules also apply.

SHOULD (server; content): Send content that lets the user recognize the source of the conflict. Table row
The server SHOULD generate content that includes enough information for a user to recognize the source of the conflict. RFC 9110 §15.5.10

The same rule is in the response obligations table and its JSON.