RESTful API response status code disambiguation

Question

I'm developing a RESTful API and have a question about the most appropriate response status codes for certain scenarios.

Consider the case where the client makes a GET request for a resource. How can I disambiguate a "not found" response for the case where the resource legitimately does not exist, vs. the case where there may be a minor service interruption (during deployment, etc).

Answer 1

Send a 404 status code for "Not found"

Send some 500-series error for error conditions on the server-side.

Answer 2

The W3C defines very specific status codes for nearly all cases you can think of. For your specific needs:

• Not Found: 404
• Service Unavailable: 503