HTTP Status 424 or 500 for error on external dependency

Question

I am trying to create a service that has 2 dependencies. One of the dependencies is internally managed while the 2nd requires an external http outbound call to a third party API. The sequence requires the updating the resource and then executing the http outbound call.

So my question is, on the event of a failure on the 2nd step, what is the correct http status code to return?

Should the response be 424 or 500 with a message body explaining the encountered error?

• 424: Method Failure - Indicates the method was not executed on a particular resource within its scope because some part of the method's execution failed causing the entire method to be aborted.
• 500: Internal Server Error.

Answer 1

The failure you're asking about is one that has occurred within the internals of the service itself, so a 5xx status code range is the correct choice. 503 Service Unavailable looks perfect for the situation you've described.

5xx codes are for telling the client that even though the request was fine, the server has had some kind of problem fulfilling the request. On the other hand, 4xx codes are used to tell the client it has done something wrong (and that the server is just fine, thanks). Sections 10.4 and 10.5 of the HTTP 1.1 spec explain the different purposes of 4xx and 5xx codes.

Status code 424 is defined in the WebDAV standard and is for a case where the client needs to change what it is doing - the server isn't experiencing any problem here.

Answer 2

As second operation is an external service call, you should choose 502 or 504 according to the situations.

Quoted from: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.3

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.

10.5.4 503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay MAY be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 response.

  Note: The existence of the 503 status code does not imply that a
  server must use it when becoming overloaded. Some servers may wish
  to simply refuse the connection.

10.5.5 504 Gateway Timeout

The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI (e.g. HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed to access in attempting to complete the request.

  Note: Note to implementors: some deployed proxies are known to
  return 400 or 500 when DNS lookups time out.

Answer 3

503 Service Unavailable is appropriate if the issue is one that the server expects to be alleviated (such as if it gets a 503 from the upstream server, for instance). 502 Bad Gateway should be used for unknown errors from an upstream server, where you don't know how to respond.