Skip to content


This page explains how to apply rate limiting to APIs.

Rate limit diagram


In the realm of API management, rate limiting is one of the fundamental aspects of managing traffic to your APIs.

API-level rate limiting can help with API overuse and ensures that the overall rate limit isn't exceeded.

Good to know

  • You can configure multiple rate limits per Traefik Hub agent.
  • An API can have multiple rate limit policies.
  • You can only define one strategy per rate limit.
    For example, you could have two (or more) policies with a different number of allowed requests.

Rate limiting algorithm

Behind the scenes, Traefik Hub uses the Token Bucket algorithm to rate limit requests.

The token bucket algorithm is used to define the number of requests that can be served simultaneously.


If you set the period to 1m with a limit of 10 you can do, on average, 0.16 request per second (10/60s).
In other words, every 0.16 seconds, the bucket receives a new token

This represents the rate at which the bucket of available requests fills up.

Users spend one token for each request and after the request the token will be removed from the bucket. At the same time, it fills the bucket with new tokens at a constant rate and while there is free space in it.

If users spend tokens faster than they're refilled and the bucket is empty, requests will be rejected till new tokens are added to it.

You can configure the refilling period of a bucket in seconds, minutes or hours.

Field Description
limit The number of tokens in a bucket.
period The time period (speed) at which the tokens are added into the bucket.
Time period can be seconds, minutes or hours (s/m/h). Default value is one second.

Rate limiting strategies

Traefik Hub supports two strategies, local and distributed rate limiting.

Local rate limiting applies rate limiting policies to a single Traefik Hub agent.
If you scale an API using two Traefik Hub agents, each agent will use an own policy.

Distributed rate limiting distributes one rate limiting policy among multiple Traefik Hub agents.
If you scale an API using two Traefik Hub agents, one policy and thus one bucket configuration will be used across all Traefik Hub agents.

You can only define one strategy pre rate limit.

Local rate limiting

  • Local rate limiting is applied at the individual Traefik Hub agent, and API or API collection level. Each API or API collection enforces its own rate limits independently of other Traefik Hub agents.
  • Local rate limiting is often easier to implement and manage for smaller-scale systems and APIs.

This is the default strategy for all rate limits.

You can only use the distributed strategy if your Traefik Hub agent is configured for it.

Distributed rate limiting

Distributed rate limiting is for maintaining consistent count between different instances of the Traefik Hub agent.

  • Distributed rate limiting is applied across multiple Traefik Hub instances. It centralizes rate limiting rules and coordination among Traefik Hub agents.
  • Distributed rate limiting uses Redis to store and share rate limit counters and data across all API servers.

What's next

  • Learn how to apply local API rate limiting with CRDs (Custom Resource Definitions).
  • Learn how to apply local API rate limiting through the UI.