How should an error be returned to a REST client (if at all)? - rest

Question

I have a REST resource that returns tabular data:
http://example.org/api/tables/foo
This returns the first page of results from the foo table.
There is a query parameter to add a selection criteria to the resource:
http://example.org/api/tables/foo?id=bar
id=bar is not a free text query. Internally the server attempts to resolve bar to a known entity and creates a regular expression limiting the rows returned from foo. For this query to succeed bar must be an ID that the system is aware of - otherwise the regular expression cannot be generated appropriately.
What's the correct behavior for this resource if bar is not known to the system? I understand that 5xx responses are not appropriate since the client cannot call again and expect a different result. Is it appropriate to return a 404 response with a message detailing that bar was not recognized? Or is it better to return a 200 response (since this is a search result) with some envelope wrapping the empty search result detailing that bar could not be found? Something else entirely?

Answer 1

It all depends on your business domain.
If a call to an unknown entity is a failure in your domain - you should provide an error status code of 4xx (if I understand you correctly, the resource was not found - so a status code of 404 Not Found will be appropriate in here).
If a call to an unknown entity is ok, it just yield no results (lets say a google search that yields 0 results) you should provide a status code of 2xx.
Status codes 5xx are server error, and they tell the client that there is something wrong with the server side. In your situation there is nothing wrong with your server, so a status code of 4xx will be appropriate in here.
By the way, you don't have to use all the error codes for every error - basically if you go over you business domain, you will see that you can use only a small subset of these codes to describe your errors.
Be sure to provide a detailed message back in the response so that the person using your service will get as much details and information as possible.
If you can, provide links to online resources explaining the problem. For example, if you have a developers forum thread discussing this exact problem - provide a link to that thread.
If you have to use error codes, use string codes rather then random numbers, for example: use "UNKNOWN_ENTITY" instead of error number #9842.
Example for an error message:
{
"message" : "Unknown entity provided".
"description" : "Parameter bar is not known to the system.",
"errorCode" : "UNKNOWN_ENTITY",
"links":
[
{ "rel" : "help",
"href" : "http://myforum.com/errors/unkownEntityError",
"title" : "My Forum"
},
]
}

Answer 2

This is a question often up for debate, but most people will use 401 Unauthorized or 400 Bad Request to indicate errors. I typically use 401 for login failures / authentication failures and 400 for bad parameters. In the message body of a 400 response, I often return a message indicating the bad parameters.