Configuring Feign Timeout Settings in Standalone and Spring Cloud Environments

In this article we discuss a common interview question that also appears in real projects: how to configure Feign timeout settings.

Prerequisite Knowledge

To follow the discussion you need a basic understanding of Feign. Below is a brief overview of Feign's purpose and core concepts.

Feign's Role

Projects often need to call third‑party HTTP APIs. While you could use low‑level HTTP clients such as HttpClient, writing repetitive request‑building code quickly becomes cumbersome when many services are involved.

public class HttpClientDemo {

    public static void main(String[] args) throws Exception {
        // create an HttpClient
        HttpClient httpClient = HttpClientBuilder.create().build();

        // build a GET request
        HttpGet httpGet = new HttpGet("http://192.168.100.1:8080/order/1");

        // send request and obtain response
        HttpResponse httpResponse = httpClient.execute(httpGet);
        HttpEntity httpEntity = httpResponse.getEntity();

        // read response body
        String response = EntityUtils.toString(httpEntity);

        System.out.println("Response: " + response);
    }
}

When the number of external services grows, manually assembling requests for each service becomes tedious. Feign solves this problem by providing a declarative HTTP client.

Feign is a declarative HTTP framework. You declare an interface and annotate it; Feign generates a dynamic proxy that handles request assembly, execution, and response parsing.

Feign's Internals

Feign creates a dynamic proxy via Feign.Builder . The builder parses annotations on the interface and produces an implementation that delegates to a Client component.

The Client interface has a single method:

Response execute(Request request, Options options)

The Request argument contains the URL, HTTP method, headers, and body. The Options argument encapsulates timeout settings (connect and read). The Response object holds status code, headers, and body.

Setting Timeout When Using Feign Standalone

Feign can be used directly as an HTTP client. It offers two ways to configure timeouts.

1. Via Feign.Builder

Feign.Builder contains an Options property. If you do not set it, the defaults are 10 seconds for connection timeout and 60 seconds for read timeout.

Feign.builder()
    .options(new Request.Options(5, TimeUnit.SECONDS, 5, TimeUnit.SECONDS, true))
    .target(UserApi.class, "http://localhost:8088");

Demo code:

public interface UserApi {
    @RequestLine("GET /user/{userId}")
    User queryUser(@Param("userId") Integer userId);
}

public class FeignDemo {
    public static void main(String[] args) {
        UserApi client = Feign.builder()
            // set both connect and read timeout to 5 seconds
            .options(new Request.Options(5, TimeUnit.SECONDS, 5, TimeUnit.SECONDS, true))
            .target(UserApi.class, "http://localhost:8088");
        User user = client.queryUser(123);
    }
}

When the Options are not supplied, Feign uses its default implementation Client.Default .

2. Via Method Parameter

You can also add an Options parameter to the interface method:

@RequestLine("GET /user/{userId}")
User queryUser(@Param("userId") Integer userId, Request.Options options);

Calling the method with a custom Options overrides the builder configuration:

User user = client.queryUser(123, new Request.Options(3, TimeUnit.SECONDS, 3, TimeUnit.SECONDS, true));

Method‑parameter timeout has higher precedence than the builder‑level setting.

Feign Timeout Configuration in Spring Cloud

In a Spring Cloud application Feign is wrapped with additional annotations. The usage changes slightly:

Replace Feign’s native annotations with Spring MVC annotations.

Add @FeignClient on the interface.

Enable scanning with @EnableFeignClients .

Even though Feign is usually combined with Ribbon, it can be used alone by specifying the url attribute on @FeignClient .

1. Declaring an Options Bean

Spring creates the Feign.Builder automatically. If an Options bean is present, Spring injects it into the builder:

@Configuration
public class FeignConfiguration {
    @Bean
    public Request.Options options() {
        return new Request.Options(8, TimeUnit.SECONDS, 8, TimeUnit.SECONDS, true);
    }
}

2. Using Application Properties

Timeouts can also be set in application.yml (or application.properties ):

feign:
  client:
    config:
      default:
        connectTimeout: 10000
        readTimeout: 10000

When both a bean and properties are defined, the property value takes precedence because Spring follows the rule: convention > configuration > code.

Feign with Ribbon

When Feign is combined with Ribbon, Ribbon’s timeout settings become effective. Ribbon can also perform load balancing and retries.

ribbon:
  ConnectTimeout: 5000
  ReadTimeout: 5000

If no explicit Feign timeout is provided, Feign falls back to Ribbon’s defaults (1 second for both connect and read), which may cause unexpected timeouts.

Feign with Hystrix

When Hystrix wraps Feign calls, Hystrix’s own timeout (default 1 second) can cut off a request even if Feign’s timeout is larger. To avoid premature fallback, increase Hystrix’s timeout:

hystrix:
  command:
    default:
      execution:
        isolation:
          thread:
            timeoutInMilliseconds: 30000

The recommended rule is:

Hystrix timeout ≥ (connect timeout + read timeout) × retry count

Summary

Standalone Feign: configure via Feign.Builder or method‑parameter Options .

Spring Cloud standalone Feign: method‑parameter Options , configuration‑file Options , or an @Bean of type Request.Options .

Feign + Ribbon: set timeouts through Ribbon configuration.

Feign + Hystrix: adjust Hystrix’s timeout to be larger than the combined Feign timeouts and retry count.

If this article helped you, feel free to share, like, or bookmark it. Thank you!