HTTP 409 Conflict — Duplicate Resources, Optimistic Locking & Fix

When to Return 409

Use 409 when the request would create a duplicate (email already exists), when an edit conflicts with a concurrent update (optimistic locking), or when a state transition is invalid given the current state.

Common Causes

• Registering an email address that already exists
• Concurrent edit conflict (stale ETag / version mismatch)
• Trying to complete an already-completed order
• Uploading a file that already exists
• Creating a resource with a duplicate unique key

HTTP Response Example

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

{"error": "Conflict", "message": "Email already registered", "field": "email"}

Code Examples

app.post('/users', async (req, res) => {
  const existing = await db.users.findByEmail(req.body.email)
  if (existing) {
    return res.status(409).json({
      error: 'Conflict',
      message: 'A user with this email already exists',
      field: 'email',
    })
  }
  const user = await db.users.create(req.body)
  res.status(201).json(user)
})

export async function POST(request: Request) {
  const { email } = await request.json()
  const exists = await db.users.findByEmail(email)
  if (exists) {
    return Response.json(
      { error: 'Conflict', message: 'Email already registered' },
      { status: 409 }
    )
  }
  const user = await db.users.create({ email })
  return Response.json(user, { status: 201 })
}

Related Status Codes