Search code examples
httphttp-status-codes

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

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?

Solution

  • 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.)