Lecture 250: Troubleshooting common mistakes when using API Gateway and Service Discovery

First, picture an airport. There are air traffic controllers (API Gateway) who manage departures and arrivals of planes (requests) and make sure they reach the correct runways (microservices). But what if the controllers lose contact with the planes (services become unavailable)? Or they send planes to the wrong runways (wrong routes)? Or there’s confusion when multiple planes are sent to the same runway (overload)?

API Gateway and Service Discovery, like airport controllers, depend on many factors, and the smallest mistake can turn into a cascading disaster. Let's walk through the most frequent issues developers run into and how to fix them.

TOP-10 common mistakes when using API Gateway and Service Discovery

1. Incorrect request routing

Problem description:
You set up the API Gateway and wrote routes, but requests stubbornly don't reach the intended microservice. The culprit might be a typo in the route configuration or an incorrect predicate.

How to avoid it:

• Use clear and logical request paths. For example, instead of /api/v1/foo/bar use something obvious like /users/1/orders.
• Always test routes locally using tools like Postman or curl.
• Remember predicate order: predicates in Spring Cloud Gateway are processed in the order they are declared.

Example:

spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: http://localhost:8081
          predicates:
            - Path=/users/**

Check: is the path /users/** specified correctly? Will requests to that path be served?

2. Authentication and authorization issues

Problem description:
Client requests are rejected even though they should be allowed. This can be caused by misconfigured OAuth2, tokens, or access roles.

How to avoid it:

• Regularly verify token and role configurations. If you use JWT, make sure the signature and expiration are correct.
• Don't forget to test authorization manually or with automated tests.

Example:

@Bean
public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
    return http.csrf().disable()
               .authorizeExchange()
               .pathMatchers("/admin/**").hasRole("ADMIN")
               .anyExchange().authenticated()
               .and().build();
}

Make sure roles (ADMIN, USER) are correctly set up in the database.

3. No load balancing

Problem description:
The system crashes because one microservice is hit with a flood of requests while others sit idle. You forgot to configure request balancing.

How to avoid it:

• Use built-in load balancing strategies supported by the API Gateway, e.g., Round Robin, Random, or Least Connections.
• Enable load monitoring (for example, via Actuator) and tweak settings as needed.

Example load balancing config:

spring:
  cloud:
    gateway:
      routes:
        - id: load-balanced-service
          uri: lb://user-service
          predicates:
            - Path=/users/**

Check: the uri: lb://service-name config uses load balancing via Eureka.

4. Bugs in Eureka integration

Problem description:
Microservices aren't visible in the Eureka registry or they constantly disappear from it.

How to avoid it:

• Check network settings between the Eureka Server and clients. Make sure correct addresses and ports are used.
• Ensure all microservices send heartbeats.

Client Eureka config example:

eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/
  instance:
    prefer-ip-address: true

When address conflicts happen, use prefer-ip-address: true.

5. Incorrect CORS configuration

Problem description:
Frontend requests are blocked because the API Gateway isn't configured to allow cross-origin requests.

How to avoid it:

• Configure CORS on the Gateway to allow your frontend domains.
• Make sure allowed methods (GET, POST) and headers are set correctly.

Example:

@Bean
public WebFluxConfigurer corsConfigurer() {
    return new WebFluxConfigurer() {
        @Override
        public void addCorsMappings(CorsRegistry registry) {
            registry.addMapping("/**")
                    .allowedOrigins("http://frontend.com")
                    .allowedMethods("GET", "POST");
        }
    };
}

6. Monitoring blind spots

Problem description:
It's hard to tell whether the problem is in the API Gateway, microservices, or the network. Metrics and logging are missing.

How to avoid it:

• Enable request and response logging in the Gateway.
• Set up Actuator for metrics and visualize them with Grafana or Prometheus.

logging:
  level:
    org.springframework.web: DEBUG
    org.springframework.cloud.gateway: DEBUG

7. Filter problems

Problem description:
Filters added to the API Gateway behave incorrectly or cause unexpected errors (for example, changing the request body breaks the JSON structure).

How to avoid it:

• Test filters in isolation.
• Only write custom filters when necessary; use built-in Spring Cloud Gateway filters for standard tasks.

Example filter to add a header:

@Bean
public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
    return builder.routes()
            .route("add_header_route", r -> r.path("/add-header")
                    .filters(f -> f.addRequestHeader("X-Custom-Header", "MyValue"))
                    .uri("http://example.com"))
            .build();
}

8. No fallback mechanisms

Problem description:
When one microservice fails, requests just "hang". Clients get a terrible impression of your app.

How to avoid it:

• Implement fallbacks using Resilience4j or Hystrix to handle failures.
• Return friendly error messages.

@Bean
public RouteLocator fallbackRouteLocator(RouteLocatorBuilder builder) {
    return builder.routes()
            .route("fallback_route", r -> r.path("/service")
                    .filters(f -> f.fallbackHeaders()
                            .fallbackUri("forward:/fallback"))
                    .uri("lb://service"))
            .build();
    }
}

9. Services constantly re-registering

Problem description:
Eureka Server shows services constantly registering and disappearing (flapping).

How to avoid it:

• Check timeout settings (eureka.instance.lease-expiration-duration-in-seconds) to reduce re-registration frequency.
• Make sure heartbeats work correctly.

10. API Gateway overload

Problem description:
A massive stream of requests overloads the API Gateway, making the whole system unreachable.

How to avoid it:

• Configure rate limiting for the API Gateway.
• Use horizontal scaling.

Example rate limiting config:

spring:
  cloud:
    gateway:
      routes:
        - id: limited-route
          predicates:
            - Path=/limited
          filters:
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 5
                redis-rate-limiter.burstCapacity: 10

Conclusion

Configuring API Gateway and Service Discovery is both an art and an engineering task. Mistakes can look small but have catastrophic consequences. To minimize them, test every setting and always plan for resilience. As developers, you should be a little paranoid — and that's totally fine! Any misconfiguration can turn into a production outage — and nobody wants that, right?