Conflict Errors — Handling Duplicate and State Conflicts

In this tutorial, you will learn about Conflict Errors. We cover key concepts, practical examples, and best practices to help you master this topic.

Conflict errors (409) indicate the request conflicts with the current state of the resource, such as duplicate creation attempts, stale version updates, or business rule violations.

Common Scenarios

Duplicate resource creation (email already exists), stale version updates (optimistic locking conflict), state transition violations (cancelling a shipped order), and unique constraint violations.

Implementation

app.post("/api/users", async (req, res) => {
  const existing = await findUserByEmail(req.body.email);
  if (existing) {
    return res.status(409).json({
      status: 409,
      error: "conflict",
      message: "A user with this email already exists",
      conflictField: "email",
      conflictValue: req.body.email,
      existingUserId: existing.id
    });
  }
  const user = await createUser(req.body);
  res.status(201).json(user);
});

Common Mistakes

1. Returning 400 for conflicts — Use 409 for conflicts, 400 for malformed requests.
2. No conflict details — Tell the client what caused the conflict.
3. Not exposing identifiers — Help clients find the conflicting resource.

Practice Questions

1. When should you return 409 Conflict?
2. What information should a 409 response include?
3. How does 409 differ from 400?

What's Next

In the next lesson, you will learn rate limit error handling.