What Java exception class to use for HTTP errors?

Quick answer

In Spring you have exactly what you want:

• HttpClientErrorException - Exception thrown when an HTTP 4xx is received.
• HttpServerErrorException - Exception thrown when an HTTP 5xx is received.

And a recommended practice

Minimally, you should differentiate exceptions related to business logic (e.g., insufficient balance, email address is not valid) from other exceptions (e.g., server not available, unsupported media type, SQLException).

In our REST API, we have a library for Java clients that parses responses and throws only three different exceptions:

• 400, 401, 403, 404, 409, 422: throw MyBusinessException, which contains a message that can be shown to the end user. The message comes in the response body (exception handling on the service side), but if not present we have a default message specific to each status code.
• 405, 412, 415: throw HttpClientErrorException with a message that is specific to each status code.
• other 4xx codes: throw HttpClientErrorException with a generic message.
• 5xx codes: throw HttpServerErrorException with a generic message.

All these exceptions are unchecked.

Check out the page on Exception Handling for HttpClient

To answer your question though there appears to be an org.apache.commons.httpclient.HttpException class that is probably a good fit.

If you do need a custom exception class for this I would think java.io.IOException would be the correct super class to use.

I found this exception on Apache HTTP Client 4.5.7:

...
import org.apache.http.client.HttpResponseException;

...
StatusLine statusLine = response.getStatusLine();
if(statusLine.getStatusCode() != 200) {
    throw new HttpResponseException(statusLine.getStatusCode(), statusLine.getReasonPhrase());
}
...

The sample of result is:

Exception in thread "main" org.apache.http.client.HttpResponseException: status code: 400, reason phrase: Bad Request

I'd say this depends on what you are using the HTTPClient for. For example, the PayPal SDK uses HttpClient to transmit API calls to the PayPal server, but fails to check the HTTP response code when it's done. I patched my copy so that if the response code isn't 200 it throws a PayPal FatalException, with an appropriate message. That's because the caller isn't interested in the HTML or any of the details of this HTTP post, and isn't even interested in the fact that we're using HTTP as a transport. If the call is successful then the body of the response contains transaction details, which are extracted and placed into a response object; otherwise it contains HTML which is useless. HTTP is just the transport in this case, so certain response codes indicate errors which can be reported using exceptions. Because this is part of the PayPal SDK, I used a PayPal Exception class. In some other system or library, I'd use a subtype of whatever exceptions that library already uses. For example, if I were writing a GMail library, which accesses GMail accounts, I'd probably create a GMailException class, and subclass that for the different kinds of exceptions the library runs into. Alternatively, you can use something like IOException.

The reason HttpClient makes you check response codes is because the response may be useful even if the response code is not 200. Some websites put useful text on a 404 page, either providing something useful for the user to do, or a search form, or just a helpful error message. Depending on your use case you may want to just show the response content rather than throw an exception.

There is org.apache.commons.httpclient.HttpException if you want a library exception. We have also sometimes created our own for specific purposes, both creating an exception for specific HTTP status codes and a generic one for and unexpected status code.