Mastering Multiple WebClient Calls in Spring: Combine & Optimize

In modern microservices architectures, your application often needs to fetch data from multiple upstream services to build a response. Doing this sequentially—calling Service A, waiting, then calling Service B—adds latency linearly. For a user-facing API, that's a death sentence. I've seen production outages where a chain of five sequential calls caused a 5-second response time, leading to timeouts and angry customers.

Spring WebClient, the reactive HTTP client introduced in Spring 5, lets you make multiple calls simultaneously and combine their results without blocking threads. But doing it right is harder than it looks. I've debugged countless incidents where developers used block() inside reactive pipelines, turning a non-blocking flow into a thread-pool disaster.

In this guide, I'll show you the battle-tested patterns for making and combining multiple WebClient calls. We'll cover reactive composition with zip(), error handling for partial failures, production configuration, and the gotchas that the official docs gloss over. By the end, you'll be able to build fast, resilient services that aggregate data from multiple sources without breaking a sweat.

Why Parallelism Matters: The Latency Tax

Every network call adds latency. If you make three sequential HTTP calls, each taking 100ms, your total response time is 300ms plus overhead. In a microservices world, that tax multiplies. I've seen services that called five upstream APIs sequentially, resulting in a 1.5-second response time for a simple dashboard. The fix? Parallelize with WebClient.

Spring WebClient is built on Project Reactor, which gives you non-blocking I/O out of the box. Instead of waiting for each response, you can fire all requests at once and combine them when they're ready. The key operators are Mono.zip() for combining multiple Mono results, and Flux.zip() for combining streams.

Let's start with a naive sequential approach that you should never use in production:

// BAD: Sequential calls - adds latency
Mono<User> userMono = webClient.get()
    .uri("/users/{id}", userId)
    .retrieve()
    .bodyToMono(User.class);

Mono<Order> orderMono = userMono.flatMap(user ->
    webClient.get()
        .uri("/orders?userId={id}", user.getId())
        .retrieve()
        .bodyToMono(Order.class)
);

// Total time: user call + order call = 200ms if each is 100ms

The Right Way: Parallel Composition with zip()

When calls are independent, use Mono.zip() to fire them concurrently. Here's the correct pattern:

// GOOD: Parallel calls using Mono.zip
Mono<User> userMono = webClient.get()
    .uri("/users/{id}", userId)
    .retrieve()
    .bodyToMono(User.class);

Mono<Order> orderMono = webClient.get()
    .uri("/orders?userId={id}", userId)
    .retrieve()
    .bodyToMono(Order.class);

Mono<DashboardResponse> dashboard = Mono.zip(
    userMono, orderMono
).map(tuple -> {
    User user = tuple.getT1();
    Order order = tuple.getT2();
    return new DashboardResponse(user, order);
});

// Total time: max(100ms, 100ms) = 100ms (plus overhead)

Handling Partial Failures Gracefully

In the real world, upstream services fail. If you use plain zip(), a single failure causes the whole combined Mono to fail. That's often too harsh. Instead, you want to gracefully degrade: if the user service fails, still return the order data with a null user, or a default.

The pattern is to use onErrorResume() per call to provide a fallback:

Mono<User> userMono = webClient.get()
    .uri("/users/{id}", userId)
    .retrieve()
    .bodyToMono(User.class)
    .onErrorResume(e -> {
        log.warn("Failed to fetch user, using default", e);
        return Mono.just(User.DEFAULT);
    })
    .timeout(Duration.ofSeconds(2));

Mono<Order> orderMono = webClient.get()
    .uri("/orders?userId={id}", userId)
    .retrieve()
    .bodyToMono(Order.class)
    .onErrorResume(e -> Mono.just(Order.EMPTY))
    .timeout(Duration.ofSeconds(3));

Mono<DashboardResponse> dashboard = Mono.zip(
    userMono, orderMono
).map(tuple -> new DashboardResponse(tuple.getT1(), tuple.getT2()));

What the Official Docs Won't Tell You

The Spring docs show you how to use zip(), but they don't warn you about these production pitfalls:

1. block() is a silent killer: The docs mention block() for testing, but developers use it in controllers. It blocks the event loop thread, causing thread starvation. I've debugged a production incident where a single block() call brought down a payment service. Never use block() in a reactive pipeline.
2. Connection pooling defaults are too low: The default maxConnections is 500, but the pendingAcquireTimeout is 60 seconds. Under load, you'll see "Connection pool exhausted" errors. Increase maxConnections and reduce the acquire timeout.
3. zip() doesn't cancel on error: If one Mono fails, the others continue running. This wastes resources. Use zipWhen() or onErrorMap() to cancel remaining calls if you don't need partial results.
4. Timeouts are not transitive: A timeout on a single call doesn't propagate to the zip(). If you want the whole operation to timeout, wrap the zip() in a .timeout() as well.
5. Memory leaks from unread bodies: If you don't consume the response body (e.g., you only check status), the connection is not released. Always read the body or use exchangeToMono() with proper cleanup.

@Bean
public WebClient webClient() {
    ConnectionProvider provider = ConnectionProvider.builder("custom")
        .maxConnections(1000)
        .pendingAcquireTimeout(Duration.ofSeconds(30))
        .maxIdleTime(Duration.ofSeconds(20))
        .build();

    HttpClient httpClient = HttpClient.create(provider)
        .responseTimeout(Duration.ofSeconds(5));

    return WebClient.builder()
        .clientConnector(new ReactorClientHttpConnector(httpClient))
        .build();
}

Combining Multiple Calls with Flux for Lists

Sometimes you need to make multiple calls based on a list of items. For example, fetch details for each user ID in a list. You can use Flux.flatMap() to fire requests concurrently, but be careful about concurrency limits:

List<String> userIds = List.of("1", "2", "3");

Flux<User> users = Flux.fromIterable(userIds)
    .flatMap(id -> webClient.get()
        .uri("/users/{id}", id)
        .retrieve()
        .bodyToMono(User.class)
        .onErrorResume(e -> Mono.empty()) // skip failed
        .timeout(Duration.ofSeconds(2)),
        5 // concurrency limit: max 5 parallel calls
    );

// Collect results
Mono<List<User>> userList = users.collectList();

Advanced: Conditional Composition with zipWhen

Sometimes you need to make a second call only if the first succeeds. For example, fetch user details, then fetch their orders only if the user is active. zipWhen() is perfect for this:

Mono<DashboardResponse> dashboard = webClient.get()
    .uri("/users/{id}", userId)
    .retrieve()
    .bodyToMono(User.class)
    .zipWhen(user -> {
        if (user.isActive()) {
            return webClient.get()
                .uri("/orders?userId={id}", user.getId())
                .retrieve()
                .bodyToMono(Order.class);
        } else {
            return Mono.just(Order.EMPTY);
        }
    })
    .map(tuple -> new DashboardResponse(tuple.getT1(), tuple.getT2()));