409 Conflict
409 Conflict is used in cases where the HTTP request was valid, but the
current state of the server prevents it from being executed.
This is useful for APIs. A few hypothetical examples:
- A user wants to add a file to a folder, but the folder doesn’t exist yet.
- Amazon S3 uses it when you try to delete a bucket that’s not empty.
- You’re creating a new blog post, but it refers to a category that was deleted.
The key here is that it might be possible to run the same request again after this conflict is resolved, by for example:
- Creating the folder you’re trying to upload to.
- Removing all items from the S3 bucket before removing it.
- Re-creating or undeleting the category you’re trying to assign to the blog post.
The HTTP specification recommends that the HTTP response body contains information in the response body that the client or user can use to resolve the conflict.
Example
HTTP/1.1 409 Conflict
Content-Type: text/plain
You tried to upload a file to a folder that doesn't exist. Create the folder
and try again!
Usage
If you are building an API, it’s a good idea to emit 409 conflict for these situations. It can be seen as a more specific code than 400 and sometimes 403.
You might even be able to define a response body that a client can use to automatically resolve the conflict, or at least inform the user in a standard way what was wrong.
References
- RFC7231, Section 6.5.8 - 409 Conflict