[Spring Boot Basics] Gọi API bên ngoài với RestClient trong Spring Boot: GET, POST, xử lý lỗi và timeout

import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpServer;
 
import java.io.IOException;
import java.io.OutputStream;
import java.net.InetSocketAddress;
import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.Executors;
import java.util.concurrent.atomic.AtomicLong;
 
/**
 * A fake supplier API for local experiments.
 * Run: java SupplierApiStub.java [port] [stockDelaySeconds]
 */
public class SupplierApiStub {
 
    private static final AtomicLong NEXT_ORDER_ID = new AtomicLong(5001);
    private static int port;
    private static int stockDelaySeconds;
 
    public static void main(String[] args) throws IOException {
        port = args.length > 0 ? Integer.parseInt(args[0]) : 8133;
        stockDelaySeconds = args.length > 1 ? Integer.parseInt(args[1]) : 0;
        HttpServer server = HttpServer.create(new InetSocketAddress(port), 0);
        server.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
        server.createContext("/", SupplierApiStub::handle);
        server.start();
        System.out.println("Supplier API stub on port " + port + ", stock delay " + stockDelaySeconds + "s");
    }
 
    private static void handle(HttpExchange exchange) throws IOException {
        String method = exchange.getRequestMethod();
        String path = exchange.getRequestURI().getRawPath();
        String query = exchange.getRequestURI().getRawQuery();
        String body = new String(exchange.getRequestBody().readAllBytes(), StandardCharsets.UTF_8);
        log(exchange, method, path, query, body);
 
        if (method.equals("GET") && path.equals("/api/suppliers")) {
            send(exchange, 200, """
                    [{"id":7,"name":"Hanoi Keyboards","country":"VN","leadTimeDays":5,"rating":4.8},\
                    {"id":8,"name":"Saigon Switches","country":"VN","leadTimeDays":12,"rating":4.1}]""");
        } else if (method.equals("GET") && path.equals("/api/suppliers/search")) {
            send(exchange, 200, "[]");
        } else if (method.equals("GET") && path.equals("/api/suppliers/7")) {
            exchange.getResponseHeaders().add("X-Rate-Limit-Remaining", "99");
            send(exchange, 200, """
                    {"id":7,"name":"Hanoi Keyboards","country":"VN","leadTimeDays":5,"rating":4.8}""");
        } else if (method.equals("GET") && path.startsWith("/api/suppliers/")) {
            send(exchange, 404, """
                    {"code":"SUPPLIER_NOT_FOUND","message":"No supplier with id %s"}"""
                    .formatted(path.substring("/api/suppliers/".length())));
        } else if (method.equals("POST") && path.equals("/api/purchase-orders")) {
            if (body.contains("\"quantity\":0") || body.contains("\"quantity\":-")) {
                send(exchange, 400, """
                        {"code":"INVALID_QUANTITY","message":"quantity must be positive"}""");
                return;
            }
            long id = NEXT_ORDER_ID.getAndIncrement();
            exchange.getResponseHeaders().add("Location", "http://localhost:" + port + "/api/purchase-orders/" + id);
            send(exchange, 201, body.replaceFirst("\\{", "{\"id\":" + id + ",\"status\":\"PENDING\","));
        } else if (method.equals("PUT") && path.startsWith("/api/purchase-orders/")) {
            send(exchange, 200, body);
        } else if (method.equals("DELETE") && path.startsWith("/api/purchase-orders/")) {
            exchange.sendResponseHeaders(204, -1);
            exchange.close();
        } else if (method.equals("GET") && path.equals("/api/price-list")) {
            send(exchange, 500, """
                    {"code":"INTERNAL","message":"price list is being rebuilt"}""");
        } else if (method.equals("GET") && path.startsWith("/api/stock/")) {
            sleep(stockDelaySeconds);
            send(exchange, 200, "{\"sku\":\"" + path.substring("/api/stock/".length()) + "\",\"available\":42}");
        } else {
            send(exchange, 404, "{\"code\":\"NO_ROUTE\"}");
        }
    }
 
    private static void log(HttpExchange exchange, String method, String path, String query, String body) {
        StringBuilder line = new StringBuilder(method + " " + path + (query == null ? "" : "?" + query));
        for (String name : new String[] {"Accept", "Content-Type", "X-Api-Key", "X-Request-Id", "User-Agent"}) {
            String value = exchange.getRequestHeaders().getFirst(name);
            if (value != null) {
                line.append("\n    ").append(name).append(": ").append(value);
            }
        }
        if (query != null) {
            for (String pair : query.split("&")) {
                line.append("\n    param: [").append(URLDecoder.decode(pair, StandardCharsets.UTF_8)).append("]");
            }
        }
        if (!body.isEmpty()) {
            line.append("\n    body: ").append(body);
        }
        System.out.println(line);
    }
 
    private static void send(HttpExchange exchange, int status, String json) throws IOException {
        byte[] bytes = json.getBytes(StandardCharsets.UTF_8);
        exchange.getResponseHeaders().add("Content-Type", "application/json");
        exchange.sendResponseHeaders(status, bytes.length);
        try (OutputStream out = exchange.getResponseBody()) {
            out.write(bytes);
        }
    }
 
    private static void sleep(int seconds) {
        try {
            Thread.sleep(seconds * 1000L);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }
}

java SupplierApiStub.java 8133

Supplier API stub on port 8133, stock delay 0s

+--- org.springframework.boot:spring-boot-starter-restclient -> 4.1.1
|    +--- org.springframework.boot:spring-boot-starter:4.1.1
|    +--- org.springframework.boot:spring-boot-starter-jackson:4.1.1
|    \--- org.springframework.boot:spring-boot-restclient:4.1.1
|         +--- org.springframework.boot:spring-boot-http-converter:4.1.1
|         +--- org.springframework.boot:spring-boot:4.1.1 (*)
|         \--- org.springframework.boot:spring-boot-http-client:4.1.1

RestClient plain = RestClient.create();
RestClient withBaseUrl = RestClient.create("http://localhost:8133");
RestClient configured = RestClient.builder()
        .baseUrl("http://localhost:8133")
        .build();

org.springframework.web.client.RestClientException: Error while extracting response for type [com.example.demo.supplier.Supplier] and content type [application/json]
  caused by org.springframework.http.converter.HttpMessageNotReadableException: JSON parse error: Unrecognized property "rating" (class com.example.demo.supplier.Supplier), not marked as ignorable
  caused by tools.jackson.databind.exc.UnrecognizedPropertyException: Unrecognized property "rating" (class com.example.demo.supplier.Supplier), not marked as ignorable (4 known properties: "id", "name", "country", "leadTimeDays")

***************************
APPLICATION FAILED TO START
***************************
 
Description:
 
Parameter 0 of method supplierRestClient in com.example.demo.supplier.SupplierClientConfig required a bean of type 'org.springframework.web.client.RestClient$Builder' that could not be found.
 
 
Action:
 
Consider defining a bean of type 'org.springframework.web.client.RestClient$Builder' in your configuration.

package com.example.demo.supplier;
 
import org.springframework.boot.context.properties.ConfigurationProperties;
 
@ConfigurationProperties("app.supplier-api")
public record SupplierApiProperties(String baseUrl, String apiKey) {
}

app.supplier-api.base-url=http://localhost:8133
app.supplier-api.api-key=demo-key-123

package com.example.demo.supplier;
 
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestClient;
 
@Configuration
@EnableConfigurationProperties(SupplierApiProperties.class)
public class SupplierClientConfig {
 
    @Bean
    RestClient supplierRestClient(RestClient.Builder builder, SupplierApiProperties properties) {
        return builder
                .baseUrl(properties.baseUrl())
                .defaultHeader("X-Api-Key", properties.apiKey())
                .build();
    }
}

package com.example.demo.supplier;
 
public record Supplier(long id, String name, String country, int leadTimeDays) {
}

package com.example.demo.supplier;
 
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestClient;
 
@Component
public class SupplierClient {
 
    private final RestClient restClient;
 
    public SupplierClient(RestClient supplierRestClient) {
        this.restClient = supplierRestClient;
    }
 
    public Supplier findSupplier(long id) {
        return restClient.get()
                .uri("/api/suppliers/{id}", id)
                .retrieve()
                .body(Supplier.class);
    }
}

Supplier[id=7, name=Hanoi Keyboards, country=VN, leadTimeDays=5]

GET /api/suppliers/7
    X-Api-Key: demo-key-123
    User-Agent: Java-http-client/21.0.6

    public List<Supplier> findSuppliers() {
        return restClient.get()
                .uri("/api/suppliers")
                .retrieve()
                .body(new ParameterizedTypeReference<List<Supplier>>() {});
    }

[Supplier[id=7, name=Hanoi Keyboards, country=VN, leadTimeDays=5], Supplier[id=8, name=Saigon Switches, country=VN, leadTimeDays=12]]

ResponseEntity<Supplier> entity = supplierRestClient.get()
        .uri("/api/suppliers/{id}", 7)
        .retrieve()
        .toEntity(Supplier.class);
System.out.println("status       = " + entity.getStatusCode());
System.out.println("content type = " + entity.getHeaders().getContentType());
System.out.println("rate limit   = " + entity.getHeaders().getFirst("X-Rate-Limit-Remaining"));
System.out.println("body         = " + entity.getBody());
System.out.println("headers      = " + entity.getHeaders());

status       = 200 OK
content type = application/json
rate limit   = 99
body         = Supplier[id=7, name=Hanoi Keyboards, country=VN, leadTimeDays=5]
headers      = [content-length:"78", content-type:"application/json", date:"Sat, 12 Sep 2026 07:41:52 GMT", x-rate-limit-remaining:"99"]

String q = "C++ & bàn phím";
 
// A: the value itself goes into queryParam(), build() gets no variables
supplierRestClient.get()
        .uri(uriBuilder -> uriBuilder.path("/api/suppliers/search")
                .queryParam("q", q)
                .queryParam("country", "VN")
                .build())
        .retrieve()
        .toBodilessEntity();
 
// B: queryParam() holds a URI variable, build() receives the value
supplierRestClient.get()
        .uri(uriBuilder -> uriBuilder.path("/api/suppliers/search")
                .queryParam("q", "{q}")
                .queryParam("country", "VN")
                .build(q))
        .retrieve()
        .toBodilessEntity();
 
// C: a URI template string with variables
supplierRestClient.get()
        .uri("/api/suppliers/search?q={q}&country={country}", q, "VN")
        .retrieve()
        .toBodilessEntity();
 
// D: string concatenation
supplierRestClient.get()
        .uri("/api/suppliers/search?q=" + q + "&country=VN")
        .retrieve()
        .toBodilessEntity();

GET /api/suppliers/search?q=C++%20%26%20b%C3%A0n%20ph%C3%ADm&country=VN
    X-Api-Key: demo-key-123
    User-Agent: Java-http-client/21.0.6
    param: [q=C   & bàn phím]
    param: [country=VN]
GET /api/suppliers/search?q=C%2B%2B%20%26%20b%C3%A0n%20ph%C3%ADm&country=VN
    X-Api-Key: demo-key-123
    User-Agent: Java-http-client/21.0.6
    param: [q=C++ & bàn phím]
    param: [country=VN]
GET /api/suppliers/search?q=C%2B%2B%20%26%20b%C3%A0n%20ph%C3%ADm&country=VN
    X-Api-Key: demo-key-123
    User-Agent: Java-http-client/21.0.6
    param: [q=C++ & bàn phím]
    param: [country=VN]
GET /api/suppliers/search?q=C++%20&%20b%C3%A0n%20ph%C3%ADm&country=VN
    X-Api-Key: demo-key-123
    User-Agent: Java-http-client/21.0.6
    param: [q=C   ]
    param: [ bàn phím]
    param: [country=VN]

package com.example.demo.supplier;
 
public record PurchaseOrderRequest(long supplierId, String sku, int quantity) {
}

package com.example.demo.supplier;
 
public record PurchaseOrder(long id, String status, long supplierId, String sku, int quantity) {
}

    public ResponseEntity<PurchaseOrder> placeOrder(PurchaseOrderRequest order) {
        return restClient.post()
                .uri("/api/purchase-orders")
                .contentType(MediaType.APPLICATION_JSON)
                .body(order)
                .retrieve()
                .toEntity(PurchaseOrder.class);
    }
 
    public PurchaseOrder updateOrder(PurchaseOrder order) {
        return restClient.put()
                .uri("/api/purchase-orders/{id}", order.id())
                .contentType(MediaType.APPLICATION_JSON)
                .body(order)
                .retrieve()
                .body(PurchaseOrder.class);
    }
 
    public ResponseEntity<Void> cancelOrder(long id) {
        return restClient.delete()
                .uri("/api/purchase-orders/{id}", id)
                .retrieve()
                .toBodilessEntity();
    }

ResponseEntity<PurchaseOrder> created = supplierClient.placeOrder(new PurchaseOrderRequest(7, "KB-87", 20));
System.out.println("status   = " + created.getStatusCode());
System.out.println("location = " + created.getHeaders().getLocation());
System.out.println("body     = " + created.getBody());
 
PurchaseOrder order = created.getBody();
PurchaseOrder updated = supplierClient.updateOrder(
        new PurchaseOrder(order.id(), order.status(), order.supplierId(), order.sku(), 25));
System.out.println("updated  = " + updated);
 
ResponseEntity<Void> cancelled = supplierClient.cancelOrder(order.id());
System.out.println("cancel   = " + cancelled.getStatusCode() + ", hasBody=" + cancelled.hasBody() + ", body=" + cancelled.getBody());

status   = 201 CREATED
location = http://localhost:8133/api/purchase-orders/5001
body     = PurchaseOrder[id=5001, status=PENDING, supplierId=7, sku=KB-87, quantity=20]
updated  = PurchaseOrder[id=5001, status=PENDING, supplierId=7, sku=KB-87, quantity=25]
cancel   = 204 NO_CONTENT, hasBody=false, body=null

POST /api/purchase-orders
    Content-Type: application/json
    X-Api-Key: demo-key-123
    User-Agent: Java-http-client/21.0.6
    body: {"supplierId":7,"sku":"KB-87","quantity":20}
PUT /api/purchase-orders/5001
    Content-Type: application/json
    X-Api-Key: demo-key-123
    User-Agent: Java-http-client/21.0.6
    body: {"id":5001,"status":"PENDING","supplierId":7,"sku":"KB-87","quantity":25}
DELETE /api/purchase-orders/5001
    X-Api-Key: demo-key-123
    User-Agent: Java-http-client/21.0.6

package com.example.demo.supplier;
 
public record UpstreamError(String code, String message) {
}

try {
    supplierClient.findSupplier(99);
}
catch (RestClientResponseException ex) {
    System.out.println("class         = " + ex.getClass().getName());
    System.out.println("message       = " + ex.getMessage());
    System.out.println("status        = " + ex.getStatusCode() + " / " + ex.getStatusText());
    System.out.println("body string   = " + ex.getResponseBodyAsString());
    System.out.println("body as type  = " + ex.getResponseBodyAs(UpstreamError.class));
    System.out.println("content type  = " + ex.getResponseHeaders().getContentType());
}

class         = org.springframework.web.client.HttpClientErrorException$NotFound
message       = 404 Not Found: "{"code":"SUPPLIER_NOT_FOUND","message":"No supplier with id 99"}"
status        = 404 NOT_FOUND / Not Found
body string   = {"code":"SUPPLIER_NOT_FOUND","message":"No supplier with id 99"}
body as type  = UpstreamError[code=SUPPLIER_NOT_FOUND, message=No supplier with id 99]
content type  = application/json

    public String priceList() {
        return restClient.get()
                .uri("/api/price-list")
                .retrieve()
                .body(String.class);
    }

class         = org.springframework.web.client.HttpServerErrorException$InternalServerError
message       = 500 Internal Server Error: "{"code":"INTERNAL","message":"price list is being rebuilt"}"
status        = 500 INTERNAL_SERVER_ERROR / Internal Server Error
body string   = {"code":"INTERNAL","message":"price list is being rebuilt"}
body as type  = UpstreamError[code=INTERNAL, message=price list is being rebuilt]
content type  = application/json

package com.example.demo.supplier;
 
public class SupplierNotFoundException extends RuntimeException {
 
    public SupplierNotFoundException(long id) {
        super("Supplier " + id + " does not exist");
    }
}

    public Supplier findSupplier(long id) {
        return restClient.get()
                .uri("/api/suppliers/{id}", id)
                .retrieve()
                .onStatus(status -> status.value() == 404, (request, response) -> { 
                    throw new SupplierNotFoundException(id); 
                }) 
                .body(Supplier.class);
    }

com.example.demo.supplier.SupplierNotFoundException: Supplier 99 does not exist

package com.example.demo.supplier;
 
import org.springframework.http.HttpStatusCode;
 
public class SupplierApiException extends RuntimeException {
 
    private final HttpStatusCode upstreamStatus;
 
    public SupplierApiException(HttpStatusCode upstreamStatus, String upstreamBody) {
        super("Supplier API answered " + upstreamStatus.value() + ": " + upstreamBody);
        this.upstreamStatus = upstreamStatus;
    }
 
    public HttpStatusCode getUpstreamStatus() {
        return upstreamStatus;
    }
}

    @Bean
    RestClient supplierRestClient(RestClient.Builder builder, SupplierApiProperties properties) {
        return builder
                .baseUrl(properties.baseUrl())
                .defaultHeader("X-Api-Key", properties.apiKey())
                .defaultStatusHandler(HttpStatusCode::isError, (request, response) -> { 
                    throw new SupplierApiException(response.getStatusCode(), 
                            new String(response.getBody().readAllBytes(), StandardCharsets.UTF_8)); 
                }) 
                .build();
    }

for (Runnable call : new Runnable[] {
        () -> supplierClient.findSupplier(99),
        () -> supplierClient.priceList(),
        () -> supplierClient.placeOrder(new PurchaseOrderRequest(7, "KB-87", 0)) }) {
    try {
        call.run();
    }
    catch (Exception ex) {
        System.out.println(ex.getClass().getName() + ": " + ex.getMessage());
    }
}

com.example.demo.supplier.SupplierNotFoundException: Supplier 99 does not exist
com.example.demo.supplier.SupplierApiException: Supplier API answered 500: {"code":"INTERNAL","message":"price list is being rebuilt"}
com.example.demo.supplier.SupplierApiException: Supplier API answered 400: {"code":"INVALID_QUANTITY","message":"quantity must be positive"}

    public Optional<Supplier> findSupplierOrEmpty(long id) {
        return restClient.get()
                .uri("/api/suppliers/{id}", id)
                .exchange((request, response) -> {
                    if (response.getStatusCode().isSameCodeAs(HttpStatus.NOT_FOUND)) {
                        return Optional.empty();
                    }
                    if (response.getStatusCode().isError()) {
                        throw new SupplierApiException(response.getStatusCode(),
                                new String(response.getBody().readAllBytes(), StandardCharsets.UTF_8));
                    }
                    return Optional.of(response.bodyTo(Supplier.class));
                });
    }

7  -> Optional[Supplier[id=7, name=Hanoi Keyboards, country=VN, leadTimeDays=5]]
99 -> Optional.empty

org.springframework.web.client.ResourceAccessException: I/O error on GET request for "http://localhost:8139/api/suppliers/7": null
  caused by java.net.ConnectException: null
  caused by java.nio.channels.ClosedChannelException: null

package com.example.demo.supplier;
 
import org.springframework.boot.ApplicationRunner;
import org.springframework.boot.http.client.ClientHttpRequestFactoryBuilder;
import org.springframework.boot.http.client.HttpClientSettings;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
 
@Configuration
class HttpClientReport {
 
    @Bean
    ApplicationRunner printHttpClient(ClientHttpRequestFactoryBuilder<?> requestFactoryBuilder,
            HttpClientSettings httpClientSettings) {
        return args -> {
            System.out.println("factory builder = " + requestFactoryBuilder.getClass().getSimpleName());
            System.out.println("request factory = " + requestFactoryBuilder.build(httpClientSettings).getClass().getName());
            System.out.println("settings        = " + httpClientSettings);
        };
    }
}

factory builder = JdkClientHttpRequestFactoryBuilder
request factory = org.springframework.http.client.JdkClientHttpRequestFactory
settings        = HttpClientSettings[cookieHandling=null, redirects=null, connectTimeout=null, readTimeout=null, sslBundle=null, inetAddressFilter=null]

package com.example.demo.supplier;
 
public record StockLevel(String sku, int available) {
}

    public StockLevel stock(String sku) {
        return restClient.get()
                .uri("/api/stock/{sku}", sku)
                .retrieve()
                .body(StockLevel.class);
    }

void timed(String label, int boundSeconds, Callable<?> call) throws Exception {
    ExecutorService executor = Executors.newSingleThreadExecutor(r -> {
        Thread t = new Thread(r, "timed-call");
        t.setDaemon(true);
        return t;
    });
    long start = System.nanoTime();
    Future<?> future = executor.submit(call);
    try {
        Object result = future.get(boundSeconds, TimeUnit.SECONDS);
        System.out.printf("%s: returned after %d ms: %s%n", label, (System.nanoTime() - start) / 1_000_000, result);
    }
    catch (TimeoutException ex) {
        System.out.printf("%s: still waiting after %d ms, giving up%n", label, (System.nanoTime() - start) / 1_000_000);
    }
    catch (ExecutionException ex) {
        Throwable cause = ex.getCause();
        System.out.printf("%s: threw after %d ms%n", label, (System.nanoTime() - start) / 1_000_000);
        System.out.println(cause.getClass().getName() + ": " + cause.getMessage());
        for (Throwable c = cause.getCause(); c != null; c = c.getCause()) {
            System.out.println("  caused by " + c.getClass().getName() + ": " + c.getMessage());
        }
    }
}

timed("plain builder client, GET /api/stock/KB-87", 60,
        () -> stubClient.get().uri("/api/stock/{sku}", "KB-87").retrieve().body(StockLevel.class));
timed("plain builder client, GET http://10.255.255.1/api/stock/KB-87", 100,
        () -> unroutableClient.get().uri("/api/stock/{sku}", "KB-87").retrieve().body(StockLevel.class));

plain builder client, GET /api/stock/KB-87: still waiting after 60005 ms, giving up
plain builder client, GET http://10.255.255.1/api/stock/KB-87: still waiting after 100005 ms, giving up

plain builder client, GET /api/stock/KB-87: threw after 3023 ms
org.springframework.web.client.ResourceAccessException: I/O error on GET request for "http://localhost:8133/api/stock/KB-87": Request cancelled
  caused by java.net.http.HttpTimeoutException: Request cancelled
plain builder client, GET http://10.255.255.1/api/stock/KB-87: threw after 2004 ms
org.springframework.web.client.ResourceAccessException: I/O error on GET request for "http://10.255.255.1/api/stock/KB-87": HTTP connect timed out
  caused by java.net.http.HttpConnectTimeoutException: HTTP connect timed out
  caused by java.net.ConnectException: HTTP connect timed out

RestClient.create(), GET /api/stock/KB-87: returned after 10067 ms: StockLevel[sku=KB-87, available=42]

package com.example.demo.supplier;
 
import java.time.Duration; 
 
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.bind.DefaultValue; 
 
@ConfigurationProperties("app.supplier-api")
public record SupplierApiProperties(String baseUrl, String apiKey) { 
public record SupplierApiProperties( 
        String baseUrl, 
        String apiKey, 
        @DefaultValue("2s") Duration connectTimeout, 
        @DefaultValue("5s") Duration readTimeout) { 
}

    @Bean
    RestClient supplierRestClient(RestClient.Builder builder, SupplierApiProperties properties) { 
    RestClient supplierRestClient(RestClient.Builder builder, SupplierApiProperties properties, 
            ClientHttpRequestFactoryBuilder<?> requestFactoryBuilder, HttpClientSettings httpClientSettings) { 
        ClientHttpRequestFactory requestFactory = requestFactoryBuilder 
                .build(httpClientSettings.withTimeouts(properties.connectTimeout(), properties.readTimeout())); 
        return builder
                .baseUrl(properties.baseUrl())
                .defaultHeader("X-Api-Key", properties.apiKey())
                .requestFactory(requestFactory) 
                .defaultStatusHandler(HttpStatusCode::isError, (request, response) -> {
                    throw new SupplierApiException(response.getStatusCode(),
                            new String(response.getBody().readAllBytes(), StandardCharsets.UTF_8));
                })
                .build();
    }

supplierClient.stock(KB-87): threw after 5013 ms
org.springframework.web.client.ResourceAccessException: I/O error on GET request for "http://localhost:8133/api/stock/KB-87": Request cancelled
  caused by java.net.http.HttpTimeoutException: Request cancelled
supplierRestClient.mutate() to 10.255.255.1: threw after 1002 ms
org.springframework.web.client.ResourceAccessException: I/O error on GET request for "http://10.255.255.1/api/stock/KB-87": HTTP connect timed out
  caused by java.net.http.HttpConnectTimeoutException: HTTP connect timed out
  caused by java.net.ConnectException: HTTP connect timed out

factory builder = SimpleClientHttpRequestFactoryBuilder
request factory = org.springframework.boot.http.client.SimpleClientHttpRequestFactoryBuilder$SimpleClientHttpsRequestFactory
settings        = HttpClientSettings[cookieHandling=null, redirects=null, connectTimeout=PT2S, readTimeout=PT3S, sslBundle=null, inetAddressFilter=null]

Caused by: org.springframework.beans.BeanInstantiationException: Failed to instantiate [org.springframework.boot.http.client.ClientHttpRequestFactoryBuilder]: Factory method 'clientHttpRequestFactoryBuilder' threw exception with message: org/apache/hc/client5/http/classic/HttpClient
	... 85 common frames omitted
Caused by: java.lang.NoClassDefFoundError: org/apache/hc/client5/http/classic/HttpClient
	... 88 common frames omitted
Caused by: java.lang.ClassNotFoundException: org.apache.hc.client5.http.classic.HttpClient
	... 94 common frames omitted

package com.example.demo.supplier;
 
import java.io.IOException;
import java.util.UUID;
 
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
 
import org.springframework.http.HttpRequest;
import org.springframework.http.client.ClientHttpRequestExecution;
import org.springframework.http.client.ClientHttpRequestInterceptor;
import org.springframework.http.client.ClientHttpResponse;
 
public class SupplierApiLoggingInterceptor implements ClientHttpRequestInterceptor {
 
    private static final Logger log = LoggerFactory.getLogger(SupplierApiLoggingInterceptor.class);
 
    @Override
    public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution)
            throws IOException {
        String requestId = UUID.randomUUID().toString();
        request.getHeaders().set("X-Request-Id", requestId);
        long start = System.nanoTime();
        try {
            ClientHttpResponse response = execution.execute(request, body);
            log.info("{} {} -> {} in {} ms [{}]", request.getMethod(), request.getURI(),
                    response.getStatusCode().value(), elapsedMillis(start), requestId);
            return response;
        }
        catch (IOException ex) {
            log.warn("{} {} failed after {} ms [{}]: {}", request.getMethod(), request.getURI(),
                    elapsedMillis(start), requestId, ex.toString());
            throw ex;
        }
    }
 
    private static long elapsedMillis(long start) {
        return (System.nanoTime() - start) / 1_000_000;
    }
}

                .defaultStatusHandler(HttpStatusCode::isError, (request, response) -> {
                    throw new SupplierApiException(response.getStatusCode(),
                            new String(response.getBody().readAllBytes(), StandardCharsets.UTF_8));
                })
                .requestInterceptor(new SupplierApiLoggingInterceptor()) 
                .build();

INFO 38589 --- [demo] [           main] c.e.d.s.SupplierApiLoggingInterceptor    : GET http://localhost:8133/api/suppliers/7 -> 200 in 23 ms [772e8377-7220-45e4-b8a5-ce28207db4a6]
INFO 38589 --- [demo] [           main] c.e.d.s.SupplierApiLoggingInterceptor    : GET http://localhost:8133/api/suppliers/99 -> 404 in 1 ms [5c6c0d15-5cae-468e-9216-41c680c1fdd7]
INFO 38589 --- [demo] [           main] c.e.d.s.SupplierApiLoggingInterceptor    : GET http://localhost:8133/api/price-list -> 500 in 0 ms [5ce0e643-0a62-4d89-8afd-3442d38fc6fb]
INFO 38589 --- [demo] [           main] c.e.d.s.SupplierApiLoggingInterceptor    : POST http://localhost:8133/api/purchase-orders -> 201 in 7 ms [2c606114-c282-48c0-bfbb-da3300747e07]
WARN 38589 --- [demo] [           main] c.e.d.s.SupplierApiLoggingInterceptor    : GET http://localhost:8139/api/suppliers/7 failed after 1 ms [b0574b9b-fd11-4100-9ca8-28d028fbf655]: java.net.ConnectException

GET /api/suppliers/7
    X-Api-Key: demo-key-123
    X-Request-Id: 772e8377-7220-45e4-b8a5-ce28207db4a6
    User-Agent: Java-http-client/21.0.6

logging.level.org.springframework.web.client=DEBUG

DEBUG 38589 --- [demo] [           main] o.s.web.client.DefaultRestClient         : Reading to [com.example.demo.supplier.Supplier]
DEBUG 38589 --- [demo] [           main] o.s.web.client.DefaultRestClient         : Writing [PurchaseOrderRequest[supplierId=7, sku=KB-87, quantity=20]] as "application/json" with org.springframework.http.converter.json.JacksonJsonHttpMessageConverter
DEBUG 38589 --- [demo] [           main] o.s.web.client.DefaultRestClient         : Reading to [com.example.demo.supplier.PurchaseOrder]

package com.example.demo.supplier;
 
import java.net.http.HttpConnectTimeoutException;
import java.net.http.HttpTimeoutException;
 
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.client.ResourceAccessException;
 
@RestControllerAdvice
public class UpstreamFailureHandler {
 
    @ExceptionHandler(SupplierNotFoundException.class)
    ProblemDetail supplierNotFound(SupplierNotFoundException ex) {
        return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
    }
 
    @ExceptionHandler(SupplierApiException.class)
    ProblemDetail supplierApiFailed(SupplierApiException ex) {
        return ProblemDetail.forStatusAndDetail(HttpStatus.BAD_GATEWAY,
                "Supplier API answered " + ex.getUpstreamStatus().value());
    }
 
    @ExceptionHandler(ResourceAccessException.class)
    ProblemDetail upstreamUnreachable(ResourceAccessException ex) {
        Throwable cause = ex.getCause();
        if (cause instanceof HttpTimeoutException && !(cause instanceof HttpConnectTimeoutException)) {
            return ProblemDetail.forStatusAndDetail(HttpStatus.GATEWAY_TIMEOUT, "Upstream did not answer in time");
        }
        return ProblemDetail.forStatusAndDetail(HttpStatus.SERVICE_UNAVAILABLE, "Upstream is unreachable");
    }
}

package com.example.demo.product;
 
import com.example.demo.supplier.StockLevel;
import com.example.demo.supplier.Supplier;
import com.example.demo.supplier.SupplierClient;
 
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
 
@RestController
@RequestMapping("/api/products")
public class ProductSupplierController {
 
    private final SupplierClient supplierClient;
 
    public ProductSupplierController(SupplierClient supplierClient) {
        this.supplierClient = supplierClient;
    }
 
    @GetMapping("/{sku}/stock")
    public StockLevel stock(@PathVariable String sku) {
        return supplierClient.stock(sku);
    }
 
    @GetMapping("/suppliers/{id}")
    public Supplier supplier(@PathVariable long id) {
        return supplierClient.findSupplier(id);
    }
 
    @GetMapping("/price-list")
    public String priceList() {
        return supplierClient.priceList();
    }
}

java SupplierApiStub.java 8133 10

java -jar build/libs/demo-0.0.1-SNAPSHOT.jar --server.port=8123 --app.supplier-api.read-timeout=3s

curl -i localhost:8123/api/products/price-list

HTTP/1.1 502 
Content-Type: application/problem+json
Transfer-Encoding: chunked
Date: Sun, 13 Sep 2026 03:05:40 GMT
 
{"detail":"Supplier API answered 500","instance":"/api/products/price-list","status":502,"title":"Bad Gateway"}

curl -i localhost:8123/api/products/KB-87/stock

HTTP/1.1 504 
Content-Type: application/problem+json
Transfer-Encoding: chunked
Date: Sun, 13 Sep 2026 03:05:43 GMT
 
{"detail":"Upstream did not answer in time","instance":"/api/products/KB-87/stock","status":504,"title":"Gateway Timeout"}

curl -i localhost:8123/api/products/suppliers/7

HTTP/1.1 503 
Content-Type: application/problem+json
Transfer-Encoding: chunked
Date: Sun, 13 Sep 2026 03:05:44 GMT
Connection: close
 
{"detail":"Upstream is unreachable","instance":"/api/products/suppliers/7","status":503,"title":"Service Unavailable"}