REST API Status Code Chooser

409 or 422 for a duplicate email?

Use 409 Conflict when an existing account prevents creation under the endpoint's resource-state rules. 422 Unprocessable Content can fit an API that treats uniqueness as field validation. Document the choice and what the client should change; retrying the same request will not remove the duplicate.

RFC 9110's 409 definition concerns a conflict with current resource state; its 422 definition concerns understood, syntactically correct content whose instructions cannot be processed. Neither assigns a mandatory status to duplicate email addresses.

Authenticated administrative creation

Consider POST /admin/teams/team_123/users with {"email":"ada@example.com"}. The administrator is authenticated and authorized to create users and learn account membership within this team. Email addresses must be unique within that scope. These are two alternative API contracts for the same duplicate; choose one consistently.

409: creation conflicts with the team's user collection

The address is valid, but a user in this team already has it. Return a conflict the administrator can resolve by choosing another address or using the existing user.

HTTP/1.1 409 Conflict
Content-Type: application/problem+json
Cache-Control: no-store

{
  "type": "https://api.example.com/problems/email-conflict",
  "title": "Email already in use",
  "status": 409,
  "detail": "This email belongs to a user in this team. Choose another email or use the existing user."
}

422: the documented contract treats uniqueness as field validation

If the API reports uniqueness failures through its validation contract, identify the email field so the form can show a correction. The client must change the input or use the authorized existing-account workflow.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Cache-Control: no-store

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Request validation failed",
  "status": 422,
  "errors": [
    { "detail": "Email is already in use in this team", "pointer": "/email" }
  ]
}

Both examples use RFC 9457 Problem Details, with the body status matching the HTTP status. The example type URIs and errors extension belong to this API's contract; define your own stable types. Clients should use those identifiers and structured fields, rather than parsing human-readable messages.

Public signup needs a separate privacy decision

A public caller may not be allowed to learn whether an email is registered. OWASP's authentication guidance covers generic registration messages and warns about response-code and timing differences. Changing only the body still leaks membership if new and existing addresses receive different statuses or noticeably different processing times.

When membership must stay private, design a common accepted signup workflow, such as sending next steps by email, with the same outward status and generic body for new and existing addresses. Keep processing paths and timing comparable instead of quickly exiting only for duplicates. Use 202 only when the request is accepted for later processing; a generic response must describe what the workflow does.

Link to this worked case · Choose another outcome