3rd party API gives back 500 error, what code should my API return

Well, I think it's up to you, which error code you'll use. But if the actual functionality of your API depends on a 3rd party API, I would consider using the HTTP code 503 Service Unavailable, because your service will be unavailable until the 3rd party API won't work, no matter what HTTP code the 3rd party API returned. I would also include some details (error message) in the response payload.

Or you can return the HTTP code 200 OK and send the custom error code and message as the response payload, of course, because HTTP request to your API was actually successful. But I would prefer to use the HTTP code to indicate the state of your API endpoint.

I would mirror the HTTP codes from a 3rd party API to the user only in case your API acts as a proxy without any additional functionality.

I think the first step here would be to identify the range. A 4xx would mean the User has the chance to fix the request, which is not the case here. 2xx sounds incorrect too, as the request is not successful. That leaves us pretty much with something in the range of the 5xx.

In the 5xx range, two options look appropriate to me. A simple 500 would be fine: "There is an unspecified Server Error". 503 sounds good as well, meaning "We cannot fulfill this right now, but will be able to do so later on (optionally specify the retry span in a header).

When a client calls your API does it specify directly or indirectly that it wants your API to communicate with the 3rd party service?

• No - then for the client it will be 500, as it is still Internal Server Error from the client's perspective. Unless your API can interpret the error message from 3rd party service and derive a more specific error code.

• Yes - then 503 seems to be the most appropriate here. The error message may specify what service is unavailable.