HTTP Status 424 or 500 for error on external dependency
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
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.