409 Conflict: what it means and how to fix it

A 409 means the request clashes with the current state of the resource. Common causes, how to tell it from 422, and how to return and handle 409s in your API.

· 7 min read · By the Spot Downtime team

409 Conflict means the request was valid, but it cannot be completed because of the current state of the resource on the server. Nothing is wrong with the request on its own. It clashes with something that already exists or has changed since the client last looked.

The key idea is that a 409 is usually fixable by the client: fetch the latest state, resolve the clash, and send the request again.

Where you will see a 409

  • Duplicate creation. You POST a user with an email that is already registered, or create a resource with a name that must be unique.
  • Edit conflicts. Two people edit the same record. The second save is based on an out-of-date version, so the server refuses to overwrite the first.
  • Invalid state transition. Cancelling an order that has already shipped, or deleting a folder that is not empty.
  • Version control and package registries. A push that is not a fast-forward, or publishing a version that already exists.
  • Cloud APIs. Creating a resource that exists, or changing one that is mid-operation (a bucket being deleted, a deployment still in progress).

409 compared with similar codes

  • 400: the request itself is malformed.
  • 422: the request is well formed but the data fails validation, such as a missing field or an invalid email format. This depends only on the request.
  • 409: the data may be perfectly valid, but it conflicts with server state. The same request could succeed at a different time, or against a different state.
  • 405: the method is not supported for that URL at all.
  • 412 Precondition Failed: an If-Match or If-Unmodified-Since header you sent did not hold. Often the better choice for optimistic locking.

Many APIs are not strict about 409 versus 422 for duplicates. If a field value is already taken, either is defensible. Pick one, document it, and use it consistently.

If you are a client: how to fix it

  1. Read the response body. Good APIs say what conflicted, such as which field or which current version.
  2. Fetch the current state. Do a GET on the resource and compare it with what you tried to send.
  3. Decide how to resolve. Use the existing resource, rename yours, merge the changes, or ask the user.
  4. Retry with the updated state. Do not blindly retry the identical request. It will conflict again.

If a create call returns 409 because your own earlier attempt succeeded but the response was lost, the right move is to treat the existing resource as the result. Idempotency keys (below) make this reliable.

If you run the API: returning useful 409s

A bare "Conflict" helps nobody. Say what clashed and what the client can do about it.

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

{
  "error": "email_taken",
  "message": "A user with this email already exists.",
  "existing_id": "usr_8f2k1"
}

Optimistic locking with ETags

To prevent lost updates, send a version with each resource and require the client to send it back. With HTTP preconditions:

# Read
GET /articles/42
ETag: "v7"

# Write only if it is still version 7
PUT /articles/42
If-Match: "v7"

# Someone else saved first, so the server answers
HTTP/1.1 412 Precondition Failed

Many APIs use a version field in the body instead and return 409 when it does not match the stored value. Both work. The point is that the client never silently overwrites a change it has not seen.

Idempotency for creates

Clients retry on timeouts. Without protection, a retried POST either creates a duplicate or returns a confusing 409. Accept an Idempotency-Key header, store the result against it, and return the original response when the same key arrives again. Reserve 409 for a key reused with a different payload.

Enforce uniqueness in the database

Checking "does this exist?" and then inserting is a race. Two requests can both pass the check. Put a unique constraint in the database and map the violation to a 409:

-- PostgreSQL
ALTER TABLE users ADD CONSTRAINT users_email_key UNIQUE (email);

-- In the app: catch the unique violation (SQLSTATE 23505)
-- and return 409 instead of letting it surface as a 500.

A 500 hiding a 409

An unhandled unique-constraint error usually shows up as a 500. If you see 500s on create endpoints under load, check for this before blaming the database.

Git: 409 and non-fast-forward

Git hosting services may answer with 409 when a ref update conflicts, for example when two clients update the same branch at the same moment through an API. From the command line, the equivalent is a rejected push. Fetch, rebase or merge, then push again:

git fetch origin
git rebase origin/main
git push origin main

Should 409 trigger an alert?

Usually not, on its own. A 409 is the API doing its job: it protected data from being overwritten or duplicated. A burst of them can still be a signal, for example a client stuck in a retry loop, or a deploy that changed how conflicts are detected.

When you monitor an API, decide which statuses count as healthy. A check against a read-only endpoint should expect 200. If a monitored request legitimately returns 409 (say, a create call against an existing record), set the expected status accordingly. The API monitoring guide covers status and body assertions, and API monitoring in Spot Downtime lets you check the response rather than just reachability.

Bulk HTTP status checkerCheck the status code your URLs return, many at once.

Get new guides by email

Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.

Unsubscribe from any email with one click. See our privacy policy.

Keep reading