Which HTTP status code to use upon remote server failure? 500 or 502?

Question

I have an API that, upon a client's POST request:

1. Parse the client's request
2. Do stuff with the data in the request
3. Send a request to a remote server
4. Receives a response from the remote server
5. Do more stuff with the data in the response
6. Persist the data in a database
7. Send a response to the client

In other words, normal web server stuff.

If the remote server sends me a 500 (or any other error), should I send my client a 500 Internal Server Error or a 502 Bad Gateway?

From the RFC 7231,

6.6.3.  502 Bad Gateway

   The 502 (Bad Gateway) status code indicates that the server, while
   acting as a gateway or proxy, received an invalid response from an
   inbound server it accessed while attempting to fulfill the request.

In one hand, the 502 Bad Gateway looks like this is intended for "dumb" servers that just forwards the request to the remote server, and returns its response to the client, without much processing.

In the other hand, to not be able to access the remote server doesn't sound like a 500 Internal Server Error... more like a "Remote Server Error".

Which one should I use? 500, 502 or other?

Cami

Do you expect the client to actually act differently between a 500 and 502 error? After all, both just basically mean that something went wrong, directly or indirectly, with the server. I would think an app client, for instance, wouldn't need such granularity. – Adamite

@TimBiegeleisen, the client would act the same on all 5xx errors I guess. – Cami

I would go with the answer below. I think 500 sort of already includes 502 within it. If you are paranoid/meticulous, you could still log the 502 on your own server. Then, any client 500 you could easily trace back to being caused by an actual 502. – Adamite

502 should only be returned by a real gateway. An application server should return 500. – Super

Answer 1

I'd go with 500.

It doesn't really matter - both are part of the 5xx series of errors meaning "we screwed up, not you" - so exactly what went wrong isn't really something you need to attempt to convey in the error code that comes back. 500 is generic, well understood, and clear in its meaning, so I'd just use that and not overcomplicate things.

To address your specific points.

In one hand, the 502 Bad Gateway looks like this is intended for "dumb" servers that just forwards the request to the remote server, and returns its response to the client, without much processing.

It's all convention of course, but I'd say you're reasonably correct in this analysis.

In the other hand, to not be able to access the remote server doesn't sound like a 500 Internal Server Error... more like a "Remote Server Error".

I'd argue it's still an internal server error, just an internal server error that's been caused by a remote server somewhere else (and that is a detail your users arguably don't need to know.)

Leyva

Answer 2

I would argue that you should not return a 500 unless "your own" service fails. However, you are also correct in thinking that 502 is more intended for "dumb" gateways that simply forward a request and do not do other processing.

My take on it is that the more appropriate method would be to handle it the same way you would handle "we had to call a database and that failed", or another similar situation. Specifically, the way you describe the processing indicates that you're doing enough processing that you certainly aren't "just" a forwarding agent, which means that the fact that the outbound call is made via HTTP is just incidental — it is just a service (in fact, one of multiple services, based on your description) that you call as part of the processing.

Whether that means something like returning a 503 (to indicate temporary unavailability of the service) or a different failure code is then entirely a question of how you expect to signal any case where there is an error accessing a necessary resource. This also results in consistent behavior from your application on that type of failure, and obscures a detail that the caller almost certainly has no need to know about.

My personal practice is to consider 500 errors to be appropriate only for unexpected failures happening, as a fall-back / catch-all way for the server to handle "the code blew up without telling me what to actually return". A caller should, in an ideal world, never see them and they should always be considered a bug. I'm certain there are folks that would disagree with that stance, but my experience is that it is extremely rare to encounter a situation where there wasn't some more appropriate code available (even if it might not be especially more informative).

Shama