409

Conflict

4xx Client Error

ELI5

There's a conflict - what you're trying to do clashes with something that already exists or the current state.

Server perspective

Use 409 when the request is valid but conflicts with the current resource or system state.

When to use

•Return 409 for duplicate unique values, stale versions, or concurrent edits
•Use it when the client can resolve the conflict and submit a new request
•Duplicate resource creation (e.g., username taken)
•Version conflicts in updates
•Concurrent modification conflicts
•Business rule violations due to current state

How to respond

•Explain the conflicting field, resource, or version in the response body
•Include current version metadata when it helps the client reconcile

Headers to consider

•No status-specific header is required; include ETag, version, or conflict metadata when it helps clients reconcile state.

Response body

•Include a concise conflict code and enough detail for client recovery

Server-side pitfalls

•Use 422 for semantic validation errors that are not state conflicts
•Use 412 when an explicit conditional header failed
•Validation errors (use 422 Unprocessable Content)
•Bad request format (use 400 Bad Request)
•Authorization issues (use 403 Forbidden)

Examples

Username already exists

Request:

POST https://api.example.test/api/users

# Body
{
  "username": "john_doe"
}

Response:

409 Conflict

# Headers
Content-Type: application/json

# Body
{
  "error": "conflict"
}

Username "john_doe" is already taken by another user

References

Related Status Codes

Unprocessable Content

Your request looks right, but the data doesn't make sense according to our business rules. Fix the data and try again.

Precondition Failed

You said 'only do this if that thing is true', but that thing turned out to be false, so I didn't do anything.