REST API status code for upstream service failure?

Question

Designing a RESTful API which has some elements that depend on upstream services (e.g. database, another web service, etc). In the case where the application itself is in a valid state, and can still be used, but one of those upstream services cannot be reached (either due to a network issue, or whatever), is there a more appropriate status code to use than HTTP 500?

HTTP 500 feels inappropriate to me because the problem isn't (as the RFC defines) an "internal server error". The server is fine, and still able to process other requests without melting down, it's just got degraded functionality until that other service comes back online.

I thought about 502 - Bad Gateway because the application is effectively acting as a proxy for this other service (kinda), or perhaps 503 - Service Unavailable since it's a service which is in fact unavailable, but they didn't feel exactly right. Especially the last one, since it has the connotation of being unavailable due to load or too many requests to process.

Answer 1

You shouldn't look at it from your (the api providers) perspective, but rather from the consumers perspective. You should be able to explain to your consumers how they should act when receiving a specific status code. How should they behave differently from when you send a 500?

As an api consumer, I really don't care where things went wrong. I have a single interface to work with and that is your public api. How you have chosen to implement the api behind this interface is irrelevant to me.

So for all I know, you had an internal server error. You weren't able to process my request even though it was totally legit. So you should return a status code 500 even if this was caused by a downstream system.

If it is a temporary condition however that you expect to recover from soon then it is a 503. I still don't care that this was caused by a downstream service. I only care that you tell me that you expect to recover soon, so I should retry after a while.

This is what w3.org states:

The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay MAY be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 response.

What you can (and really always should) do, is to return an error message in the body. If your api is a json api, then you should return a json formatted error message.

Don't think about looking good. Think about being explicit and predictable. The server encountered an unexpected condition, which prevented it from fulfilling the request.

Edit: You mention databases, and in the case of a database timeout it is most definitely a 500.

/JP