The next question might be: "If it's so good to document a method's API, including the exceptions it can throw, why not specify runtime exceptions too?" Runtime exceptions represent problems that are the result of a programming problem, and as such, the API client code cannot reasonably be expected to recover from them or to handle them in any way. Such problems include arithmetic exceptions, such as dividing by zero; pointer exceptions, such as trying to access an object through a null reference; and indexing exceptions, such as attempting to access an array element through an index that is too large or too small.
Ok, so unchecked exceptions are for any errors caused by programmer error. Sure.
Spring's documentation for the HttpClientErrorException (which extends RuntimeException) says the exception is for:
Exception thrown when an HTTP 4xx is received.
I can't see that this is a 'programmer error' exception.
In the scenario I'm testing, I'm making a query to a Spring RestTemplate, but the server it's querying may be down, and return a 404. This seems like a perfectly normal state of affairs, not a programming error.
Am I perhaps interacting with the Spring Framework incorrectly (ie. I should be detecting the 404 before using the RestTemplate?) or is there something else I'm not considering?