Mastering Global and Per-Route Timeouts in Spring Cloud Gateway

Environment

Spring Boot 2.4.12 with Spring Cloud Gateway 2.2.9.RELEASE.

Global Timeout Configuration

Configure HTTP connect and response timeouts for all routes in the gateway. connect-timeout is expressed in milliseconds, while response-timeout uses a java.time.Duration value.

spring:
  cloud:
    gateway:
      httpclient:
        connect-timeout: 2000
        response-timeout: 5s

Per‑Route Timeout Configuration

Individual routes can override the global settings by specifying connect-timeout and response-timeout in the route’s metadata.

spring:
  cloud:
    gateway:
      enabled: true
      discovery:
        locator:
          enabled: true
          lowerCaseServiceId: true
      default-filters:
        - StripPrefix=1
      routes:
        - id: R003
          uri: http://localhost:8082
          predicates:
            - Path=/api-x/demos/date3
          metadata:
            connect-timeout: 10000
            response-timeout: 50000

Java DSL Configuration

Using the Java DSL you can set the same timeout values programmatically.

import static org.springframework.cloud.gateway.support.RouteMetadataUtils.CONNECT_TIMEOUT_ATTR;
import static org.springframework.cloud.gateway.support.RouteMetadataUtils.RESPONSE_TIMEOUT_ATTR;

@Bean
public RouteLocator customRouteLocator(RouteLocatorBuilder routeBuilder) {
    return routeBuilder.routes()
        .route("test1", r -> r.host("*.pack.com")
            .and().path("/products")
            .filters(f -> f.addRequestHeader("api-key", "abc"))
            .uri("http://someuri")
            .metadata(RESPONSE_TIMEOUT_ATTR, 2000)
            .metadata(CONNECT_TIMEOUT_ATTR, 2000))
        .build();
}

A negative response-timeout value disables the global timeout for that route.

- id: per_route_timeouts
  uri: https://pack.com
  predicates:
    - name: Path
      args:
        pattern: /delay/{timeout}
  metadata:
    response-timeout: -1

Fluent Route Builder Example

The RouteLocatorBuilder provides a fluent API for defining multiple routes, filters, and custom metadata.

@Bean
public RouteLocator customRouteLocator(RouteLocatorBuilder builder, ThrottleGatewayFilterFactory throttle) {
    return builder.routes()
        .route(r -> r.host("**.abc.org").and().path("/image/png")
            .filters(f -> f.addResponseHeader("X-TestHeader", "foobar"))
            .uri("http://httpbin.org:80"))
        .route(r -> r.path("/image/webp")
            .filters(f -> f.addResponseHeader("X-AnotherHeader", "baz"))
            .uri("http://httpbin.org:80")
            .metadata("key", "value"))
        .route(r -> r.order(-1)
            .host("**.throttle.org").and().path("/get")
            .filters(f -> f.filter(throttle.apply(1, 1, 10, TimeUnit.SECONDS)))
            .uri("http://httpbin.org:80")
            .metadata("key", "value"))
        .build();
}

DiscoveryClient Route Locator

When the gateway is enabled with spring.cloud.gateway.discovery.locator.enabled=true, routes are created automatically from services registered in a DiscoveryClient (Eureka, Consul, Zookeeper, Nacos, etc.). The default predicate matches /serviceId/** and a rewrite filter removes the service ID from the request path.

spring.cloud.gateway.discovery.locator.predicates[0].name: Path
spring.cloud.gateway.discovery.locator.predicates[0].args[pattern]: "'/'+serviceId+'/**'"
spring.cloud.gateway.discovery.locator.predicates[1].name: Host
spring.cloud.gateway.discovery.locator.predicates[1].args[pattern]: "'**.foo.com'"
spring.cloud.gateway.discovery.locator.filters[0].name: CircuitBreaker
spring.cloud.gateway.discovery.locator.filters[0].args[name]: serviceId
spring.cloud.gateway.discovery.locator.filters[1].name: RewritePath
spring.cloud.gateway.discovery.locator.filters[1].args[regexp]: "'/' + serviceId + '/?(?<remaining>.*)'"
spring.cloud.gateway.discovery.locator.filters[1].args[replacement]: "'/${remaining}'"