Avoid OpenFeign Pitfalls: HTTP Client, Timeouts, Retries & Ribbon Settings

Pitfall 1: Use the correct Http Client

1.1 feign http client

If no special configuration is applied, OpenFeign defaults to the JDK HttpURLConnection, which lacks a connection pool and has low performance, potentially causing system failures.

Enable Apache HttpClient: feign.httpclient.enabled=true Add Maven dependency:

<dependency>
    <groupId>io.github.openfeign</groupId>
    <artifactId>feign-httpclient</artifactId>
    <version>9.3.1</version>
</dependency>

Or use OkHttpClient: feign.okhttp.enabled=true Add Maven dependency:

<dependency>
    <groupId>io.github.openfeign</groupId>
    <artifactId>feign-okhttp</artifactId>
    <version>10.2.0</version>
</dependency>

1.2 Ribbon Http Client

When OpenFeign uses Ribbon for load balancing, Ribbon also defaults to HttpURLConnection. Enable OkHttp for Ribbon:

ribbon.okhttp.enabled=true

Pitfall 2: Global timeout

Set a global timeout in application.properties:

feign.client.config.default.connectTimeout=2000
feign.client.config.default.readTimeout=60000

If not configured, the defaults are 10 seconds for connection timeout and 60 seconds for read timeout.

The read timeout must be larger than any downstream service's read timeout; otherwise calls will fail.

Example architecture (illustrated below):

If a service (e.g., serviceA) experiences a long‑running call that exceeds the read timeout, connections remain occupied, leading to resource exhaustion. Assign per‑service timeouts to avoid this.

Pitfall 3: Per‑service timeout

Configure a specific service's timeout:

feign.client.config.serviceC.connectTimeout=2000
feign.client.config.serviceC.readTimeout=60000

This overrides the global settings. Complex call chains may require further nested timeout configurations (illustrated below):

Pitfall 4: Hystrix timeout

Enable Hystrix to set per‑method timeout: feign.hystrix.enabled=true Declare a Feign client and configure Hystrix command timeout:

@FeignClient(value="serviceC", configuration=FeignMultipartSupportConfig.class)
public interface ServiceCClient {
    @GetMapping("/interface5")
    String interface5(String param);
}

hystrix.command.ServiceCClient#interface5(param).execution.isolation.thread.timeoutInMilliseconds=60000

Note: some online sources claim this works, but it may not take effect.

4.1 Using Feign timeout

Feign uses the Options class; if Feign timeout is set, it overrides other settings:

if (config.getConnectTimeout() != null && config.getReadTimeout() != null) {
    builder.options(new Request.Options(config.getConnectTimeout(), config.getReadTimeout()));
}

4.2 Using Ribbon timeout

If Feign timeout is not configured, Ribbon timeout is applied. Relevant source code:

public RibbonResponse execute(RibbonRequest request, IClientConfig configOverride) throws IOException {
    Request.Options options;
    if (configOverride != null) {
        RibbonProperties override = RibbonProperties.from(configOverride);
        options = new Request.Options(override.connectTimeout(this.connectTimeout),
                                    override.readTimeout(this.readTimeout));
    } else {
        options = new Request.Options(this.connectTimeout, this.readTimeout);
    }
    Response response = request.client().execute(request.toRequest(), options);
    return new RibbonResponse(request.getUri(), response);
}

4.3 Custom Options with RestTemplate

Use RestTemplate with an OkHttp3ClientHttpRequestFactory to set custom timeouts:

public class RestTemplateConfiguration {

    @Bean
    public OkHttp3ClientHttpRequestFactory okHttp3RequestFactory() {
        OkHttp3ClientHttpRequestFactory requestFactory = new OkHttp3ClientHttpRequestFactory();
        requestFactory.setConnectTimeout(2000);
        requestFactory.setReadTimeout(60000);
        return requestFactory;
    }

    @Bean
    @LoadBalanced
    public RestTemplate restTemplate(OkHttp3ClientHttpRequestFactory okHttp3RequestFactory) {
        return new RestTemplate(okHttp3RequestFactory);
    }
}

Added @LoadBalanced to enable Ribbon load balancing.

When using RestTemplate, the configured timeouts are applied.

Pitfall 5: Ribbon timeout

Ribbon timeout can be configured in properties:

ribbon.ConnectTimeout=2000
ribbon.ReadTimeout=11000

Feign timeout can override Ribbon timeout when both are set.

Pitfall 6: Retry disabled by default

OpenFeign disables retry by default:

@Bean
@ConditionalOnMissingBean
public Retryer feignRetryer() {
    return Retryer.NEVER_RETRY;
}

Enable retry by providing a custom Retryer:

Retryer retryer = new Retryer.Default(100, 1000, 2);

This retries after 100 ms, with a maximum interval of 1000 ms, up to two attempts (including the initial call).

Pitfall 7: Ribbon retry

7.1 Service list refresh interval

Default refresh interval is 30 seconds; shorten it for smoother deployments:

serviceC.ribbon.ServerListRefreshInterval=3

7.2 Retry settings

Configure retry behavior:

serviceC.ribbon.MaxAutoRetries=1
serviceC.ribbon.MaxAutoRetriesNextServer=1
serviceC.ribbon.OkToRetryOnAllOperations=false
serviceC.retryableStatusCodes=404,408,502,500

MaxAutoRetries does not include the initial call; setting it to 1 means one retry on the same instance before moving to the next.

Pitfall 8: Hystrix timeout

Hystrix timeout must satisfy:

hystrix.timeout >= (MaxAutoRetries + 1) * (ribbon.ConnectTimeout + ribbon.ReadTimeout)

Example configuration:

hystrix.command.ServiceCClient#interface5(param).execution.isolation.thread.timeoutInMilliseconds=15000
ribbon.ReadTimeout=8000

With this setup, Hystrix will not retry because the remaining time after the first 8 seconds is insufficient for another attempt.

Pitfall 9: Using OpenFeign as a plain HTTP client

Do not configure Ribbon‑related parameters.

When using RestTemplate, load balancing is not considered.

OpenFeign adds overhead compared to using a direct HTTP client.

For scenarios without a service registry, it is recommended to use a direct HTTP client instead of OpenFeign.