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.

update: Please note that in this specific use case, the client that uses my service does not necessarily know/need to know that the service I expose partly relies on an external API that failed during the 2nd step.

Rah

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.

Deciare

I believe that 502 or 504 should be the right HTTP error, as mentioned in the next comment by @mustafaturan. Here the external dependency did not respond. So the current server need not be branded faulty for having service unavailable. Please correct me if I am wrong. – Behoove

Same opinion: 504 if it was a timeout of the dependency, 502 if ther was another issue from a dependency, but not 503 as it is indicating 'temporary' or 'maintenance' of the server itself - and not a problem with a dependency – Frame

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.

Christchurch

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.

Disclimax

Answer 4

HTTP 424 Failed Dependency

For errors related to external dependencies, consider using HTTP 424. Unlike 5xx codes, 424 signals that the client needs to adjust its request, emphasizing a need for a change in client behavior without implying an internal server issue. It's worth noting that while 424 is defined in the WebDAV standard, it is not exclusive to WebDAV use cases and can be applied more broadly.

HTTP 502 Bad Gateway

As an alternative, HTTP 502 (Bad Gateway) can be employed, treating the external dependency as a gateway. This typically emphasizes issues related to syntax and API contract, making it a suitable choice for problems with data types or the structure of the request. In cases where your teammates may be hesitant to consider 4xx codes for client-only errors, using 502 can serve as a viable replacement, ensuring alignment with the team's coding preferences.

HTTP 400 Bad Request

Using HTTP 400 for cross-site dependency issues is generally discouraged. HTTP Status 400 (Bad Request) is designed to indicate that the server cannot or will not process the request due to a client error, such as malformed syntax or invalid parameters. In the context of external dependencies, a 400 response may mislead developers, suggesting a problem with the client's request format rather than signaling the need for a client-side adjustment to accommodate external factors.

HTTP 403 Forbidden

In unique scenarios where a third-party handles authentication for your API (e.g., using Google Auth API or Auth0 service), returning HTTP Status 403 might be considered. It's important to note that this approach is applicable only when the third party exclusively manages authentication on your behalf. It's generally recommended to avoid using HTTP 403 if the third party is not responsible for primary authentication, and instead, if there are issues with your authentication on that third-party service, consider other suitable status codes. For instance, if your authentication token has expired, a 424 Failed Dependency response might be more appropriate.

HTTP 504 Gateway Timeout

Another specific scenarios covered by mustafaturan. Can be used when server did not receive a timely response from the third-party dependency.

HTTP 500 Internal Server Error

Using code 500 can be misleading, as it may incorrectly suggest a problem with the server itself.

HTTP 503 Service Unavailable

Using code 503 is not recommended. As such code most often used during maintenance of system it could be considered by client that all other requests to the same server(all endpoints) cannot be executed successfully as well. It can cause a client will stop sending any requests to the server. Meanwhile, only one endpoint is broken.

In summary, 424 communicates a client-side adjustment is needed, while 502 underscores syntax issues within the API contract, avoiding the potential misinterpretation associated with using code 500. It's important to recognize that 424, although initially part of the WebDAV standard, can be applied beyond WebDAV scenarios.

Pseudonymous