13

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 id I am including with the user data doesn't exist in the database.

POST data: {username: 'newuser', age: 99, company_id: 34}

the company with id 34 does not exist in the database.

I was thinking whether that could be:

  • 400, kind of invalid data, but it is valid but nonexistent id
  • 404 - but it is not so clear which resource does not exist
  • 409, because it is kind of conflict and the user can resolve that by changing the company id
  • 422?
  • or 500 - because it is kind of database error while non existing id's are not allowed there
Talita
  • 805
  • 3
  • 11
  • 31

3 Answers3

19

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:

Picking the right 4xx status code

Community
  • 1
  • 1
cassiomolin
  • 124,154
  • 35
  • 280
  • 359
  • What about this status connected to WebDAV? I have seen somewhere you should use it only if you support WebDAV capabilities. – Talita Jun 01 '18 at 12:55
  • @AgataAndrzejewska Where is _somewhere_? WebDAV is a HTTP extensions and `422` is a valid HTTP status code [registered in IANA](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). – cassiomolin Jun 01 '18 at 12:57
  • 3
    I generally advise people to avoid using the status codes associated with WebDAV unless they're actively using the WebDAV standard as the basis for their API; I think it's confusing to consumers to cherry-pick a specific (although appropriate) status code from an obscure standard, ignoring everything else about that standard. https://en.wikipedia.org/wiki/Principle_of_least_astonishment – Paul Turner Jun 01 '18 at 13:00
  • CassioMazzochiMolin, I have read it in this article: https://www.keycdn.com/support/422-unprocessable-entity/ – Talita Jun 01 '18 at 13:19
  • @PaulTurner I was thinking about simplicity and clarity and 400 with a description 'invalid/incorrect company id'. The request just does not seem to have an invalid syntax problem. Generally the POST request I described seems to be not a rare case and I don't see many 422 errors returned in APIs. – Talita Jun 01 '18 at 13:20
  • 1
    @AgataAndrzejewska See the [GitHub API](https://developer.github.com/v3/?#client-errors) for example. It returns `400` for invalid JSON and wrong type of JSON values and `422` for invalid fields. – cassiomolin Jun 01 '18 at 13:28
  • 1
    @AgataAndrzejewska `422` is also [recommended](https://stackoverflow.com/a/3291292/1426227) by Julian Reschke, one of the authors of the RFCs 7230-35, the documents that define the HTTP/1.1 protocol. – cassiomolin Jun 14 '18 at 13:11
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.

Paul Turner
  • 38,949
  • 15
  • 102
  • 166
1

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).

Community
  • 1
  • 1
Jorge.V
  • 1,329
  • 1
  • 13
  • 19