# 409 Conflict

> https://http-status.org/docs/409

**Family:** 4xx Client Error

## Rationale

State conflict preventing completion (version, uniqueness).

## In Plain Terms

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

## Description

The HTTP 409 Conflict status code indicates that the request could not be completed due to a conflict with the current state of the target resource.

## Server Perspective

### Usage
- 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

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

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

### Body
- Include a concise conflict code and enough detail for client recovery

### 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)

## Client Perspective

### Pitfalls
- Do not blindly retry the same request

## Examples

### Username already exists

Username "john_doe" is already taken by another user

**Request:**
```
POST https://api.example.test/api/users

{
  "username": "john_doe"
}
```

**Response:**
```
409 Conflict
Content-Type: application/json

{
  "error": "conflict"
}
```

## Related Codes

- [422 Unprocessable Content](/docs/422.md)
- [412 Precondition Failed](/docs/412.md)