REST - what error to throw when a partly-invalid request is sent.

Question

Hey guys,

I'm developing a REST api. To simplify my question, I have an API that allows people to create a new blogpost.

Blogposts can live in categories, and categories are specified by a category id. If a user would supply a category-id that doesn't exist, which HTTP error code is the most appropriate?

404 for Not Found seems bad, so I went with 400 Bad Request for now. Is there a better one?

Answer 1

I think 404 Not Found is the most appropriate response - consider the client has tried to access a category which doesn't exist, so the perfect answer is "I can't find that category!"

Answer 2

I assume you are responding to a PUT or POST request on your blog post resource.

I would go with the 400 since the resource you are accessing with the URI is found. The blog post could have been modified if the request content had been correct.

Since this is the content of the sent query that is wrong and not the actual URI of the resource, I would stick with the 400 error.

If however, you are adding the blog post to the category by either PUTting or POSTing to the category, then you can return a 404 Not found.

Answer 3

404 has a very specific and commonly-used meaning, which is that the URL could not be found. Furthermore, some browsers will use their own 404 error page, confusing things more. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

I would recommend "406 Not Acceptable

The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request."

400 isn't bad, though.

Answer 4

What about 409 Conflict which is an application specific violation of a rule? In this this case the category ID of the Blog post must already exist. When you return the 409 conflict reply identify what the user can do to correct the situation so they can retry the POST/PUT.

Answer 5

I agree with Vincent in that, of the available defined status codes, 400 is the best. The client should know whether or not a category id is valid at the time it submits the request, and is therefore providing bad request content to the server.

With regard to some of the other answers provided:

• 404 Not Found - This is not the correct status to use, since the resource you're sending the request to actually was found - it was just a referenced resource within the provided resource that was not found.

• 406 Not Acceptable - This status is, like Evert commented, used with the Accept headers; see section 10.4.7 of RFC2616:

  The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.

• 409 Conflict - This status is intended for conflicting states of resources, typically due to modifications to the resource perhaps by another channel or thread. The RFC (section 10.4.10) gives an example:

  ...if versioning were being used and the entity being PUT included changes to a resource which conflict with those made by an earlier (third-party) request, the server might use the 409 response to indicate that it can't complete the request

HTTP does provide an alternative to 400 - if fitting, you can create your own 4XX status for this situation. In section 6.1.1 of the RFC:

HTTP status codes are extensible. HTTP applications are not required to understand the meaning of all registered status codes, though such understanding is obviously desirable.

You could therefore define your own custom "430 - Referenced Resource Not Found" or something similar. HTTP-abiding clients should, if this status is unknown to them, treat it as a 400, but if clients are being coded specifically to the API, they should be able to handle it as a 430 and work with it appropriately.