HTTP status while POST with incorrect data (using id of resource which does not exist)

Question

What would be the correct HTTP status to return when I am performing the POST request to create a new user, but one of its parameters is incorrect - the company

Answer 1

400 or 422

First of all, keep in min that it's a client error, so 5xx status codes are not suitable here. You should pick a 4xx status code then.

The most obvious options are 400 and 422:

• If the JSON is syntactically invalid, return 400.
• If JSON is syntactically valid but its content is invalid, return 422 to indicate that the request entity cannot be processed by the server.

See the following quote from the RFC 4918 (for your situation, just read JSON when it says XML):

11.2. 422 Unprocessable Entity

The 422 (Unprocessable Entity) status code means the server understands the content type of the request entity (hence a 415 (Unsupported Media Type) status code is inappropriate), and the syntax of the request entity is correct (thus a 400 (Bad Request) status code is inappropriate) but was unable to process the contained instructions. For example, this error condition may occur if an XML request body contains well-formed (i.e., syntactically correct), but semantically erroneous, XML instructions.

A similar situation was addressed in this answer.

---

For example purposes, the GitHub API v3 also returns 422 if the content of the payload contains invalid values (but is syntactically valid):

There are three possible types of client errors on API calls that receive request bodies:

1. Sending invalid JSON will result in a 400 Bad Request response. [...]

2. Sending the wrong type of JSON values will result in a 400 Bad Request response. [...]

3. Sending invalid fields will result in a 422 Unprocessable Entity response. [...]

---

Michael Kropat put together a set of diagrams that's pretty insightful when it comes to picking the most suitable status code. See the following diagram for 4xx status codes:

Answer 2

Here, this picture is very good, and I've used it many times.

Which code should I return?

I'd go with 404. The resource could exist (not a format error) but it just doesn't (and hence can't be found).

Answer 3

404 Not Found is a problematic status to return for a POST request. It implies the resource you are sending the request to doesn't exist; the caller got the URL wrong.

The most obvious (and generic) answer is: 400 Bad Request

This just indicates there is something wrong with your request (the fault lies with the caller not the server) and then express the specific detail of what went wrong in your response body. This is typically how request validation is handled.

---

The ideal answer is to make it so you add a user by sending a request to the company they are a member of:

POST /company/34
Content-Type: application/json
{
    "username": "newuser",
    "age": 99
}

This means the caller has to find a valid company resource to send the request to. If company/34 doesn't exist, a 404 Not Found response is appropriate; you tried adding a user to a company which does not exist.

This does mean your API has to be structured with resource semantics and a user has to belong to exactly one company.