What Http code should i return for “Thing not found”?

Question

i'm constructing a web-service that is used, in this particular case, to ask for information about a patron.

Let's say, for the sake of argument, that the lookup web hit is:

GET /patrons/619 HTTP/1.1

If the patron is found, i return code 200:

HTTP/1.1 200 OK

If you omit, or give an account number that is not a number, i return 400. For example the following bad requests:

GET /patrons HTTP/1.1
GET /patrons/ HTTP/1.1
GET /patrons/G619 HTTP/1.1
GET /patrons/kirsten%20guyer HTTP/1.1

all return error 400 (Bad Request), e.g.:

HTTP/1.1 400 Invalid patron number

---

i want to have a status code for patron not found, returned as the HTTP status code. For example:

GET /patrons/1322 HTTP/1.1

HTTP/1.1 404 Not Found

i've thought about using 404 (Not Found), which is a valid response (the requested resource was, really and truely, not found.) But i'm afraid people debugging it might think that it means that they spelled /patrons/ wrong.

Can anyone think of another http status code i could use?

---

Update: i'm eyeballing

204 No Content 
The server successfully processed the request, but is not returning any content. 

What say you?

---

Don't forget, that not all HTTP servers serve up HTML content. If an IIS web-server is asked for a resource called:

GET /MyStartPage.html HTTP/1.1

Then the HTTP server has to decide what to respond with. On most web-servers, a resource named /MyStartPage.html corresponds to a file sitting on the hard drive.

Whereas StackOverflow does:

GET /posts/1027301 HTTP/1.1

Which, if that resource doesn't exist, the web-server should (rightly) return 404.

Answer 1

404 Not Found is the correct thing to return, if it's a service, it's not really being used by humans but by machines, and therefore, typos, shouldn't be your first concern.

Also, there's very little you're going to be able to do to counter human behavior anyway (thinking one thing when it's really another). If you're returning a little error msg as part of the error code, everything should work out. You could even suggest to them a possible fix.

Returning a 500 when the application is doing exactly what it's designed to do also seems a little odd. 404 describes exactly the situation: Resource not found.

Answer 2

I think you should use 404. Developers of the API will understand what 404 means and will therefore follow there own usual debugging process in order to resolve the problem. Stick to the protocol.

Answer 3

Error 404 is actually a more acceptable response for this case, because the resource truly is not found. You could always have a custom error document that explains that it is the Patron ID that is not found.

A 400 error implies that the client sent malformed syntax, which is not the case in your example. Thus, you should not use this error code. It may seem that "Bad Request" is accurate, but what this actually means is there's an error in the request header syntax.

This is also not a 500 error because no error has occurred. There is no problem with the web server fulfilling the request, the fact is that the request is seeking a resource that is not present.

404 is the only appropriate response, unless you want to consider it a fully valid request, return status 200 and a page explaining that the requested Patron does not exist.

From my original comment on the question:

I don't think that a 200-level error would be appropriate either, consider the explanations at W3 w3.org/Protocols/rfc2616/rfc2616-sec10.html

Answer 4

IMHO, the HTTP response is not the proper place to handle this, as the error is not at the HTTP level. It's at the application level. One possible solution is to use the Null Object Pattern to return a null 'Patron' that conforms to the Patron interface, but indicates that no such person exists.

---

UPDATE: I've been convinced that this answer is wrong. However, I want to leave it up, as it is a potentially valid answer (depending on details not presented in the question), and I think the comments are instructive.

Answer 5

Typically if your service encounters an error that it is unable to handle, but the request is well formed, then I would think you would want to return a 500 status code.

Also, another reason why I say 500 would be appropriate is that from my experience in .NET web services, whenever I throw an exception across the wire (such as a RecordNotFound exception), the web server and client have always interpretted the response to be a 500 status code.

Either way, it would be a good idea to review this list of http status codes, and fine the one that suites your needs the best.

Answer 6

It depends on which kind of webservice you're constructing.

SOAP and XML webservices typically return 200 OK if a requested object (patron) cannot be found and encode the error type/message/description into the response document. They separate a transport level (HTTP) from the messages exchanged (XML). A 404 error (which is on the transport level) is returned only, if you request a non-existing API endpoint (wrong URL).

With a REST webservice however, you use HTTP methods and statuses directly for message exchange. REST uses different HTTP methods (GET/POST/PUT/DELETE) to specify which action is wanted and the server returns the status as the HTTP status. So in case of a REST webservice, 404 would be the proper HTTP status if a patron could not be found.

500 is inappropriate in any case I think, since 5xx means that there's been something wrong on the serverside (which isn't the case) while 4xx errors mean that there's something wrong on the client side.

Answer 7

It may be 4 years old but it is still pretty relevant. For APIs which are to be used by both borwsers and native apps, I find it is much simpler to use the HTTP codes for status indication. And if necessary use a couple of extra codes from the unallocated ones for conditions that don't have a good fit to existing HTTP codes.

Answer 8

Errors at the web service level should not just return a simple HTTP status line, but should instead return content in a valid and documented format that can be parsed by the client accessing your service. The returned document should contain an error code that is part of a documented set of codes specific to your web service, as well as a short description of the problem and optionally a more detailed description of the problem.

Answer 9

If you want to control the web service's responses via HTTP response codes, then you could indeed use a 404 to indicate this condition.

However, I would think it's more natural to have the web service's response defined entirely in the body of the HTTP response, and just return 200 for a successful communication ("I understood your request and have sent you an appropriate response"). In this case then, you'd return 200 as normal with the payload of your request (XML or JSON or whatever) indicating that no matching entity was found

I'd consider non-200 error codes similar to exceptions in conventional programming languages, and the HTTP response body more like the return code. Imagine if you were implementing this conventionally - would you throw an exception if no entity was found, or return null? Personally, given the fragile nature of network connections, I would want to reserve all HTTP-level error codes for problems in communication, and I'd much rather always return 200 OK from the service itself, along with a payload specifying the result or any service-level error.