REST API status code for upstream service failure?

Question

Developing a RESTful API that has some elements that depend on upstream services (e.g. databases, other web services, etc.). In the case where the application is in the correct state and can still be used, but one of these upstream services cannot be reached (due to a network problem or something else), is there a more suitable status code to use than HTTP 500?

The HTTP 500 feels out of place for me because the problem is not (as defined by the RFC) an “internal server error”. The server is in order and is still able to process other requests without melting, it simply degraded functionality until another service returned to the network.

I was thinking about 502 - Bad Gateway , because the application effectively acts as a proxy for this other service (kinda) or, possibly, 503 - Service Unavailable , because it is a service that is actually unavailable, but they did not feel exactly. Especially the latter, since it makes sense to be unavailable due to the load or too many processing requests.

Answer 1

You should not look at it from your perspective (api providers), but rather from the point of view of consumers.

As an api consumer, I don't care when everything went wrong. I have one interface to work with, and this is your public api. How you chose the api implementation behind this interface does not matter to me.

So, for all that I know, you had an internal server error. You could not process my request, although it was completely legal. Therefore, you must return a status code of 500.

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

Do not think about looking good. Think about being explicit and predictable. The server encountered an unexpected state, which prevented it from completing the request.

Its 500.

Edit: you specify the database, and in the case of a database timeout, it is certainly 500.

/ JP

Answer 2

It should be more like what you received from the upstream service, if its 503: Service is unavailable, then you will return 503: Service Unavailable, if its 500, you will also return 500