Traffic Management

Traffic management features give you control over how requests are routed, distributed, and protected as they flow through the gateway. These features apply to API exposures and, in the case of failover, also to API subscriptions.

Rate Limiting

Rate limiting protects your API from being overwhelmed by too many requests. You can set limits for the API as a whole (provider limits) and for individual consumers (consumer limits).

Applies to: API Exposure

Provider Limits

Provider limits cap the total number of requests your API receives, regardless of which consumer sends them. This protects your backend service from overload.

exposures:
  - type: api
    basePath: /checkout/v1
    upstream: https://checkout.internal:8080
    approval: SIMPLE
    visibility: ENTERPRISE
    rateLimit:
      provider:
        second: 100
        minute: 5000
        hour: 100000

Consumer Limits

Consumer limits cap the number of requests each individual consumer can make. You can set a default limit that applies to all consumers, and optionally override it for specific consumers.

exposures:
  - type: api
    basePath: /checkout/v1
    upstream: https://checkout.internal:8080
    approval: SIMPLE
    visibility: ENTERPRISE
    rateLimit:
      consumerDefault:
        second: 10
        minute: 500
      consumers:
        - id: hub42--team-priority--premium-app
          second: 50
          minute: 2500

Rate Limit Settings

Field	Description
provider.second	Maximum requests per second for the entire API.
provider.minute	Maximum requests per minute for the entire API.
provider.hour	Maximum requests per hour for the entire API.
consumerDefault.second	Default maximum requests per second per consumer.
consumerDefault.minute	Default maximum requests per minute per consumer.
consumerDefault.hour	Default maximum requests per hour per consumer.
consumers[].id	The client ID of the consumer to override.
consumers[].second	Overridden maximum requests per second for this consumer.
consumers[].minute	Overridden maximum requests per minute for this consumer.
consumers[].hour	Overridden maximum requests per hour for this consumer.

tip

You can also configure faultTolerant (default: true) and hideClientHeaders (default: false) on any rate limit level. When faultTolerant is enabled, the gateway continues to allow requests even if it cannot reach the configuration store. When hideClientHeaders is enabled, the rate limit response headers are hidden from consumers.

Combining Provider and Consumer Limits

You can use provider and consumer limits together. In this case, both limits are enforced independently — a request must pass both checks to be allowed through.

rateLimit:
  provider:
    second: 100
  consumerDefault:
    second: 10
  consumers:
    - id: hub42--team-priority--premium-app
      second: 50

In this example, the API accepts at most 100 requests per second in total. Each consumer is limited to 10 requests per second by default, except for premium-app which is allowed 50 requests per second.

---

Load Balancing

Load balancing distributes incoming requests across multiple backend servers. This is useful when your service runs on multiple instances or when you want to gradually shift traffic between different versions.

Applies to: API Exposure

exposures:
  - type: api
    basePath: /checkout/v1
    approval: SIMPLE
    visibility: ENTERPRISE
    loadBalancing:
      servers:
        - upstream: https://checkout-v1.internal:8080
          weight: 80
        - upstream: https://checkout-v2.internal:8080
          weight: 20

Load Balancing Settings

Field	Description
servers	A list of backend servers to distribute traffic to. At least one server is required, and up to 12 are supported.
servers[].upstream	The URL of the backend server.
servers[].weight	The relative weight for traffic distribution. Higher values receive more traffic. Default: 1. Range: 1–100.
health.httpPath	An optional HTTP path used for health checking the upstream servers.

caution

You must use either upstream (single backend) or loadBalancing (multiple backends) — not both. When you use loadBalancing, the upstream field must be omitted, and the gateway distributes traffic across the listed servers based on their weights.

---

Failover

Failover provides disaster recovery by routing traffic to backup zones when the primary zone is unavailable. This ensures high availability in multi-cloud or multi-zone deployments.

There are two independent failover mechanisms:

Mechanism	Configured on	How it works
Provider Failover	API Exposure	The gateway detects that the provider's zone is unhealthy and routes requests to a backup zone where the same API is deployed.
Consumer Failover (DTC)	API Subscription	External DNS redirects the consumer to a different zone's gateway entirely. All zones are pre-configured to accept the consumer's traffic seamlessly.

Provider Failover (API Exposure)

As an API provider, you can designate a backup zone. When consumers send requests through any gateway, the gateway checks whether your primary zone is healthy. If it is not, the gateway automatically routes requests to the backup zone instead.

Applies to: API Exposure

exposures:
  - type: api
    basePath: /checkout/v1
    upstream: https://checkout.internal:8080
    approval: SIMPLE
    visibility: ENTERPRISE
    failover:
      zones:
        - aws-zone

How it works at runtime:

1. Consumers send requests to the gateway as normal.
2. The gateway's health-check service monitors the provider's primary zone.
3. If the primary zone becomes unavailable, the gateway routes requests to the designated backup zone where a secondary route with your upstream is available.
4. When the primary zone recovers, traffic automatically returns to the normal path.

Provider Failover Settings

Field	Description
failover.zones	A list of zone names to use as backup destinations. Currently exactly one zone is supported. Maximum: 10 zones.

tip

Your API must be reachable from the backup zone. The Control Plane creates a secondary route in the backup zone with your upstream configuration, so ensure network connectivity exists between the backup zone and your backend.

---

Consumer Failover — DTC (API Subscription)

Consumer Failover, also known as Dynamic Traffic Control (DTC), takes a different approach. Instead of the gateway switching upstreams, the entire consumer is redirected to a different zone at the DNS level.

When you enable consumer failover on a subscription, the Control Plane automatically discovers all zones that support this feature and pre-configures them to accept your traffic. If your home zone goes down, external DNS redirects you to another zone's gateway — and because that gateway already knows about your subscription and trusts your identity token, the switch is transparent.

Applies to: API Subscription

subscriptions:
  - type: api
    basePath: /checkout/v1
    failover:
      enabled: true

How it works at runtime:

1. The Control Plane detects all zones with the ConsumerFailover feature enabled.
2. For each eligible zone, it creates failover routes and access grants (ConsumeRoutes) so those zones can serve your requests.
3. All affected routes are enriched with additional hostnames and trusted identity providers, so any zone's gateway accepts your token regardless of where it was issued.
4. When external DNS switches your traffic to another zone, requests flow through seamlessly — no configuration change required on your side.

Consumer Failover Settings

Field	Description
failover.enabled	Set to true to opt into consumer failover. The system automatically discovers eligible zones. Default: not set (disabled).

Prerequisites

Consumer Failover requires platform-level setup. Your platform administrator must enable the ConsumerFailover feature on the zones that should participate. See the Admin Guide: Failover for setup instructions.

---

Combining Both Mechanisms

Provider Failover and Consumer Failover work independently and can be used together for maximum resilience:

• Provider Failover protects against the provider's zone going down — the gateway re-routes to a backup where the same API is deployed.
• Consumer Failover (DTC) protects against the consumer's zone going down — DNS redirects the consumer to a healthy zone's gateway.

When both are active, consumers benefit from two layers of protection: if their own zone fails, DTC moves them to another gateway; if the provider's zone fails, that gateway's failover routes requests to the backup zone.

# Provider configures a backup zone
exposures:
  - type: api
    basePath: /checkout/v1
    upstream: https://checkout.internal:8080
    failover:
      zones:
        - aws-zone

# Consumer opts into DTC
subscriptions:
  - type: api
    basePath: /checkout/v1
    failover:
      enabled: true

---

Circuit Breaker

The circuit breaker prevents cascading failures by automatically stopping requests to an upstream service that is consistently failing. When enabled, the gateway monitors error rates and temporarily blocks traffic to unhealthy backends, giving them time to recover.

Applies to: API Exposure

exposures:
  - type: api
    basePath: /checkout/v1
    upstream: https://checkout.internal:8080
    approval: SIMPLE
    visibility: ENTERPRISE
    circuitBreaker:
      enabled: true

Circuit Breaker Settings

Field	Description
circuitBreaker.enabled	Set to true to enable the circuit breaker. Default: false.