How do I handle errors and exceptions in Java 11 HttpClient?

In Java 11, the HttpClient API provides a flexible way to handle HTTP requests and responses. When dealing with errors and exceptions, there are several strategies and patterns you can use to ensure your application can handle unexpected issues effectively while making HTTP calls.

1. Exception Types in Java 11 HttpClient

Here are some common exceptions that may occur while using the HttpClient API:

java.net.ConnectException: Thrown when a connection cannot be established.
java.net.SocketTimeoutException: Thrown if a request times out.
java.net.UnknownHostException: Thrown when the host cannot be resolved.
java.io.IOException: A general I/O error, such as a failed read/write operation.
java.net.http.HttpTimeoutException: Specific to HTTP operations when a request or response timeout is reached.

2. Handling Exceptions with `try-catch`

You can surround your HTTP client logic with a try-catch block to gracefully handle exceptions. Here is an example:

package org.kodejava.net.http;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpTimeoutException;
import java.io.IOException;
import java.net.ConnectException;
import java.net.UnknownHostException;

public class HttpClientErrorHandlingExample {
    public static void main(String[] args) {
        HttpClient httpClient = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://example.com"))
                .GET()
                .build();

        try {
            HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

            // Handle successful responses
            if (response.statusCode() == 200) {
                System.out.println("Response received: " + response.body());
            } else {
                System.out.println("Non-OK response: " + response.statusCode());
                System.out.println("Response body: " + response.body());
            }

        } catch (HttpTimeoutException e) {
            System.err.println("Request timed out: " + e.getMessage());
        } catch (UnknownHostException e) {
            System.err.println("Unknown Host: " + e.getMessage());
        } catch (ConnectException e) {
            System.err.println("Connection error: " + e.getMessage());
        } catch (IOException e) {
            System.err.println("I/O error occurred: " + e.getMessage());
        } catch (InterruptedException e) {
            System.err.println("Request interrupted: " + e.getMessage());
            Thread.currentThread().interrupt(); // Restore interrupted status
        }
    }
}

Explanation

try-catch to Isolate Block: Specific exceptions such as HttpTimeoutException or ConnectException are caught and handled to provide more detailed information about what went wrong.
Default IOException: This covers any I/O-related issue not explicitly handled by other exceptions.
Logging Errors: In this case, errors are printed to System.err, but in a production system, you should use a proper logging framework (e.g., SLF4J or Log4j).

3. Timeouts: Configure Proper Timeouts for Error Prevention

Handling timeouts properly can prevent your client from hanging indefinitely due to network issues.

HttpClient httpClient = HttpClient.newBuilder()
        .connectTimeout(java.time.Duration.ofSeconds(10)) // Timeout for connecting
        .build();

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://example.com"))
        .timeout(java.time.Duration.ofSeconds(5)) // Timeout for the request
        .GET()
        .build();

connectTimeout(): Sets the maximum time to establish a connection to the server.
request.timeout(): Sets the maximum time to wait for the request/response.

4. Handle HTTP Error Responses

Although HTTP error codes like 4xx (client error) or 5xx (server error) do not throw exceptions directly, you can handle them based on the response status code.

HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
int statusCode = response.statusCode();
if (statusCode >= 200 && statusCode < 300) {
    System.out.println("Success: " + response.body());
} else if (statusCode >= 400 && statusCode < 500) {
    System.out.println("Client error (4xx): " + response.body());
} else if (statusCode >= 500) {
    System.out.println("Server error (5xx): " + response.body());
} else {
    System.out.println("Unexpected status code: " + statusCode);
}

5. Using Asynchronous API for Better Error Control

The HttpClient supports asynchronous requests using CompletableFuture, which provides an alternative way of handling success and failure scenarios.

HttpClient httpClient = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://example.com"))
        .GET()
        .build();

httpClient.sendAsync(request, HttpResponse.BodyHandlers.ofString())
        .thenApply(HttpResponse::body)
        .thenAccept(body -> System.out.println("Response received: " + body))
        .exceptionally(e -> {
            System.err.println("Error occurred: " + e.getMessage());
            return null;
        });

thenApply: Process the response body.
exceptionally: Handle exceptions such as network failures or timeouts during the asynchronous operation.

6. Best Practices

Retry Logic: Implement retry logic for transient errors like timeouts or temporary server unavailability. Libraries like Resilience4j can simplify this.
Circuit Breakers: Protect your application from overload by using circuit breakers for repeated failures.
Logging and Monitoring: Log error details in a structured format for easy monitoring and debugging.
Test Handling: Mock failures using libraries like WireMock to test your error-handling logic.

By combining these strategies, you can handle errors and exceptions comprehensively in Java 11 HttpClient.