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:

  1. A user wants to add a file to a folder, but the folder doesn’t exist yet.
  2. Amazon S3 uses it when you try to delete a bucket that’s not empty.
  3. 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:

  1. Creating the folder you’re trying to upload to.
  2. Removing all items from the S3 bucket before removing it.
  3. 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.


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!


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.


HTTP series

This article is part of a series about the HTTP protocol. Read them all here:

Informational 1xx

Successful 2xx

Redirection 3xx

Client Error 4xx

Server Error 5xx

Bad Gateway is Toronto-based team of software engineers. We build good APIs and websites.

Want to work with me on your next project?

Email us

Web mentions