What HTTP Status code to use when a dependency/downstream (like a 3rd party API) fails?

Question

We have a route in our API which (when called) hits another 3rd party API.

e.g.

HTTP-GET /account/1

this returns some data from our database AND from .. say .. a 3rd party api like Auth0/Okta/SalesForce/whatever.

Now, if this 3rd party api call fails for any reason (fails == 4**, 5** or even a 200 OK but the content is some error message) then what error status code should I pass back to the client calling my API?

Initially I was thinking an HTTP-500-Server-Error but ... I'm not so sure now because I can prevent this error from occurring in the server if I return a nice error message back to the client. So then I thought, return an HTTP-200-OK which contains some key/value of the downstream issue/error ... but is this really OK (pun intended). To me, HTTP-200-OK is like the answer returned is really ok.

So i'm not sure what people do in this scenario.

I feel like an HTTP-500 is for errors that occur but haven't really been handled and/or accounted for.

Answer 1

Now, if this 3rd party api call fails for any reason (fails == 4**, 5** or even a 200 OK but the content is some error message) then what error status code should I pass back to the client calling my API?

APIs should be designed from the consumer's perspective. In most of situations, the API consumer wont't care if the request is fulfilled by the server they are firing a request to or by a downstream server.

If the request to the downstream server prevents your server from fulfilling the client request, you could go for 500 or 503. Alternatively you could return some cached data (if you have any) and return a 2xx status code.