Best HTTP code for a failure of an external subsystem

Question

I am working on a system that exposes a REST API. My system, to fulfill some of the requests, needs to call external APIs. These APIs sometimes fail (with internal server errors) and these failures prevent my system for completing the operation successfully.

What is the best HTTP status code that my system should return? I would like to distinguish the failures of external systems from internal failures of my system thus I am not particularly happy with returning 500.

Answer 1

For these cases I prefer HTTP 502:

10.5.3 502 Bad Gateway

The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.

Although it technically is more suitable for proxies, I think it's the closest you can get to distinguishing a server error (500) from an upstream server error.

Answer 2

You might also want to consider returning HTTP 504 in case a request to an external system timed out:

504 Gateway Timeout
The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.