APITester| Status code | 409 |
|---|---|
| Status text | Conflict |
| Category | 4xx Client Error |
| Response has body | Usually |
| Specification | RFC 9110 |
What does 409 Conflict mean?
The request conflicts with the current state of the resource. It belongs to the 4xx Client Error class, which means the request contains bad syntax or cannot be fulfilled. Something about the request needs to change.
When do APIs return 409?
Creating a record with a duplicate unique field, or a concurrent-edit collision.
How to fix a 409 Conflict
Fetch the current state first and reconcile. For optimistic concurrency, re-read the resource, take its new ETag or version, and retry.
Reproduce a 409 response
The fastest way to understand a status code is to trigger one and read the full response. Open the
API tester and send a request to https://httpbin.org/status/409 — you will
see the 409 status along with every response header the server sent. Comparing those headers against
a working request is often what reveals the cause.
When you are debugging a real endpoint, check the response headers as carefully as the body, and confirm you are using the right HTTP method for the operation.
Related 4xx status codes
400 Bad Request
The server could not understand the request because it is malformed.
401 Unauthorized
The request lacks valid authentication credentials. Despite the name, this means unauthenticated.
402 Payment Required
The request cannot be processed until payment is made.
403 Forbidden
The server understood the request and knows who you are, but refuses to authorise it.
404 Not Found
The server cannot find the requested resource.
405 Method Not Allowed
The endpoint exists but does not support the HTTP method you used.
409 Conflict FAQ
What is the difference between 409 and 422?
409 means the request is valid but clashes with the current state of the resource, such as a duplicate or an edit to a stale version. 422 means the contents of the request itself are invalid.
When should an API return 409 Conflict?
When the request cannot be completed because of the state of the resource: creating something that already exists, updating a record that changed since you read it, or deleting something still in use.
How should a client handle a 409?
Fetch the current state, resolve the difference and try again. Blindly retrying the same request will fail the same way, because the conflict is with the data rather than with timing.
See also
- 422 Unprocessable Entity — The syntax is valid but the content fails the server's validation rules.
- 423 Locked — The resource you are trying to change is locked.
- Idempotency — Why a repeated request can conflict, and how idempotency keys avoid it.
References
- RFC 9110, 409 Conflict — The specification that defines this status code.
- MDN: 409 Conflict — MDN's reference page for this status code.