Spring Cloud Gateway circuit breaker: a fallback is an API response contract

A healthy edge can still serve the wrong answer

Suppose the inventory service times out while a shopper asks for available stock. A local fallback that returns zero units looks like a confirmed out-of-stock result, although no such result was observed. Use an explicit unavailable response or a clearly marked stale snapshot. The CircuitBreaker Gateway filter can forward to a local route with a forward: URI; it does not make the downstream write safe to repeat. Retry limits and circuit state serve different purposes.

Keep the failure domain small

Name the breaker for the downstream dependency or operation whose failures should be counted together. A shared breaker for every route can turn one failing catalog call into a checkout outage. The fallback controller should avoid calling the same dependency. If it reads a cache, define the maximum accepted age and include that age in the response contract. Cache expiry alone does not prove freshness.

Prove each state transition

Test a slow downstream, an immediate 503, an open breaker, and recovery after the dependency responds again. Assert both the status and response body. Verify a protected route still passes authentication before fallback. This example configures routing only; the breaker implementation, thresholds, and timeout need an application test.

Implementation sketch

- id: inventory-read
  uri: ${INVENTORY_SERVICE_URI}
  predicates:
    - Path=/api/inventory/**
  filters:
    - name: CircuitBreaker
      args:
        name: inventoryRead
        fallbackUri: forward:/fallback/inventory

Cost and verification

A breaker adds state checks per call and can reduce load on an unhealthy dependency. A fallback that reads another remote service can move, rather than remove, the failure and latency cost.

Common Mistakes

• Do not turn an unknown stock count into a factual zero.
• Do not send a write request to a success-shaped fallback without a recovery contract.
• Do not share one circuit breaker across unrelated downstream services.

Read next

Spring Cloud Circuit Breaker: make fallback obey the original data contract, Spring Cloud Gateway retry: idempotency, buffered bodies and the byte budget, Spring Redis cache TTL versus idle expiry: GETEX changes the read contract, Spring Cloud Gateway filter order: pre and post phases reverse.