REST API status code for upstream service failure?

It should be more like whatever u receive from upstream service, if its 503: Service Unavailable then you return 503: Service Unavailable if its 500, you also return 500

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