409

Conflict

4xx Client Error

Back to list

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

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

Examples

Duplicate username

Request:POST /api/users with username "john_doe"
Response:409 Conflict with field: username

The server rejects a valid request because it conflicts with existing state.

References

Related 4xx Client Error Codes

400

Bad Request

Your request doesn't make sense or has mistakes in it. Check what you're sending and try again.

401

Unauthorized

You need to prove who you are before you can access this. Please log in or provide valid credentials.

402

Payment Required

You need to pay for this service before you can use it. Please complete payment first.

403

Forbidden

I know who you are, but you're not allowed to do this. You don't have permission for this action.

404

Not Found

The thing you're looking for doesn't exist here. It's like knocking on a door and nobody's home.

405

Method Not Allowed

You found the right place, but you're trying to do something that's not allowed here. Try a different action.

406

Not Acceptable

I can't give you the data in the format you want. I have the data, but not in XML/JSON/etc. that you asked for.

407

Proxy Authentication Required

You need to authenticate with the proxy server first before it will forward your request to the destination.

408

Request Timeout

You took too long to send your request. The server got tired of waiting and gave up.

410

Gone

This used to exist here, but it's been permanently removed and won't be coming back.

411

Length Required

You're trying to send me something, but you didn't tell me how big it is. I need to know the size before I can accept it.

412

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.

413

Content Too Large

The file or data you're trying to send is too big for me to handle. Please make it smaller.

414

URI Too Long

The web address (URL) you're using is too long for me to handle. Please make it shorter or use a different method.

415

Unsupported Media Type

I don't understand the format of data you sent me. Please send it as JSON, XML, or another format I support.

416

Range Not Satisfiable

You asked for a specific part of a file (like pages 50-60), but the file only has 10 pages. I can't give you what doesn't exist.

417

Expectation Failed

You told me to expect something specific to happen, but I can't make that happen the way you want.

418

I'm a teapot

I'm a teapot, not a coffee maker! This is an April Fools' joke code - don't use it in real APIs.

421

Misdirected Request

You sent your request to the wrong server. It's like calling the wrong phone number - the person who answered can't help you.

422

Unprocessable Content

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

WebDAV
423

Locked

This file is currently being edited by someone else and they've locked it. You'll have to wait until they're done or unlock it.

WebDAV
424

Failed Dependency

I couldn't do what you asked because something else you wanted me to do first didn't work out. It's like a domino effect - one failure caused this one.

WebDAV
425

Too Early

You're trying to do something too early in the connection process. It's like trying to order food before the restaurant is fully open.

426

Upgrade Required

You need to upgrade to a newer or different protocol to access this. It's like needing to update your app to continue using it.

428

Precondition Required

You're trying to change something, but you need to tell me what you expect it to look like first, so we don't accidentally overwrite someone else's changes.

429

Too Many Requests

Slow down! You're making too many requests too quickly. Wait a bit and try again later.

431

Request Header Fields Too Large

Your request headers (the extra information like cookies) are too big for me to handle. Clean up your cookies or make the headers smaller.

451

Unavailable For Legal Reasons

This content is blocked by law or legal restrictions in your area. It's like a book that's banned in your country.