Configuration API Reference

See HttpClientBuilder Interface in Core Interfaces for the complete API.

Quick Reference

public interface HttpClientBuilder {
    Duration connectTimeout();
    HttpClientBuilder connectTimeout(Duration timeout);

    Duration readTimeout();
    HttpClientBuilder readTimeout(Duration timeout);

    HttpClient build();
}

Timeout Types

Connect Timeout

The connect timeout determines the maximum time to wait when establishing a connection to the server. This includes:

• DNS resolution
• TCP connection establishment
• TLS/SSL handshake (if using HTTPS)

When connect timeout is exceeded:

• A RuntimeException is thrown from execute() methods
• The exception typically wraps a SocketTimeoutException or similar

Recommended values:

• Fast networks: 5-10 seconds
• Slow networks: 15-30 seconds
• Mobile networks: 30-60 seconds

Read Timeout

The read timeout determines the maximum time to wait between receiving data packets from the server. It does NOT represent the total time for the request.

Important: For each chunk of data received, the timeout is reset.

When read timeout is exceeded:

• A RuntimeException is thrown from execute() methods
• For SSE streams, ServerSentEventListener.onError() is called with the timeout exception

Recommended values:

• Standard APIs: 30-60 seconds
• LLM APIs (non-streaming): 60-120 seconds
• SSE streaming: 2-5 minutes (time between events)
• Long-polling: up to 10 minutes

SPI Configuration

Service Provider Interface (SPI)

The HttpClientBuilder is obtained via the Service Provider Interface pattern. Implementations must:

1. Implement the HttpClientBuilderFactory interface
2. Register the implementation via META-INF/services/dev.langchain4j.http.client.HttpClientBuilderFactory

Multiple Implementations

When multiple HTTP client implementations are available in the classpath:

• Use the system property langchain4j.http.clientBuilderFactory to specify which one to use
• If not specified and multiple implementations exist, an IllegalStateException is thrown

# Example: Specify which HTTP client implementation to use
java -Dlangchain4j.http.clientBuilderFactory=com.example.MyHttpClientFactory ...

Builder Reuse

HttpClientBuilder instances can be used to create multiple clients:

HttpClientBuilder builder = HttpClientBuilderLoader.loadHttpClientBuilder();

// Create client with short timeout
HttpClient fastClient = builder
    .connectTimeout(Duration.ofSeconds(5))
    .readTimeout(Duration.ofSeconds(10))
    .build();

// Create another client with long timeout
HttpClient slowClient = builder
    .connectTimeout(Duration.ofSeconds(30))
    .readTimeout(Duration.ofMinutes(2))
    .build();

Note: The behavior of builder reuse depends on the specific implementation. Some implementations may share state between builds, while others create independent configurations.

Related Documentation

• Full API: HttpClientBuilder in Core Interfaces
• Usage Guide: Timeout Configuration Guide
• Examples: Configuration Examples