Avoid the Top 9 OpenFeign Pitfalls: HTTP Clients, Timeouts, and Retries

OpenFeign is a key component in Spring Cloud that provides a declarative HTTP client, allowing remote service calls to look like local method invocations, but improper usage can lead to many pitfalls.

Pitfall 1: Use the Correct HTTP Client

1.1 Feign HTTP client

If no special configuration is applied, OpenFeign defaults to JDK's HttpURLConnection, which lacks a connection pool and has low performance. To improve this, enable Apache HttpClient: feign.httpclient.enabled=true Add the Maven dependency:

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

Or switch to OkHttpClient: feign.okhttp.enabled=true Add the corresponding 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 as well:

ribbon.okhttp.enabled=true

Pitfall 2: Global Timeout Settings

Configure a global timeout for all Feign clients:

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

If not configured, the default connect timeout is 10 seconds and the read timeout is 60 seconds (defined in feign.Request.Options ).

The read timeout must be larger than the longest external interface call; otherwise, calls exceeding the timeout will fail.

Pitfall 3: Service‑Specific Timeout Settings

Set a dedicated timeout for a particular service (e.g., serviceC):

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

If serviceC calls another service ( serviceD) that may also timeout, you may need to configure timeouts for individual interfaces.

Pitfall 4: Hystrix Timeout Configuration

Enable Hystrix to set per‑method timeouts: feign.hystrix.enabled=true Define a timeout for a specific Feign interface method:

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

Then add the property:

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

4.1 Using Feign Timeout

The timeout comes from Request.Options when both connect and read timeouts are set:

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 but Ribbon timeout is, Ribbon's timeout is used:

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 via RestTemplate

Use a dedicated RestTemplate with its own timeout settings:

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);
    }
}

The @LoadBalanced annotation enables Ribbon load balancing for the RestTemplate .

Pitfall 5: Ribbon Timeout Settings

Configure Ribbon’s own timeouts, which can be overridden by Feign’s settings:

ribbon.ConnectTimeout=2000
ribbon.ReadTimeout=11000

Pitfall 6: Retry Disabled by Default

OpenFeign’s default retryer is Retryer.NEVER_RETRY:

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

Enable retry by providing a custom Retryer.Default:

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

Pitfall 7: Ribbon Retry Configuration

7.1 Service List Refresh Interval

Reduce the default 30‑second interval to improve graceful deployments:

serviceC.ribbon.ServerListRefreshInterval=3

7.2 Retry Parameters

Maximum retries on the same instance (excluding the first call): serviceC.ribbon.MaxAutoRetries=1 Maximum retries on other instances: serviceC.ribbon.MaxAutoRetriesNextServer=1 Whether to retry all operations (including POST): serviceC.ribbon.OkToRetryOnAllOperations=false HTTP status codes that trigger a retry:

serviceC.retryableStatusCodes=404,408,502,500

Pitfall 8: Hystrix Timeout Rules

When Hystrix is enabled, its timeout must satisfy:

hystrixTimeout >= (MaxAutoRetries + 1) * (ribbonConnectTimeout + ribbonReadTimeout)

Example configuration:

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

With the above values, 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

When not using a service registry, keep in mind:

Do not configure Ribbon‑related parameters.

RestTemplate calls will not involve load balancing.

OpenFeign adds its own request assembly overhead compared to a direct HTTP client.

For scenarios without a registry, using a standard HTTP client is often simpler.