Rate limiting an API by plan in Rust: GCRA, Redis and tower-rate-tier
On this page
The problem: limiting by plan#
Almost every paid API ends up with plans: a free one with a low limit, a paid one with a higher limit and, sometimes, one with no limit at all. Limiting requests by IP doesn't help with that. You need to know who is making the request and which plan they're on, and you only learn that by looking at the request: an API key, a token or a database lookup.
And not every request weighs the same. Fetching a piece of data is cheap; generating a report or an export costs much more, so it should use up more quota. On top of that, as soon as the service runs on several instances, each with its own in-memory counter, the limit gets multiplied by the number of instances.
That's what I wrote tower-rate-tier for: a Tower middleware that limits requests according to each user's plan. It works with Axum, with Hyper and with any Tower service whose response can be built from a String (not Tonic, for now), and version 0.3.0, released on 2 October 2026, adds limits shared through Redis. In this post I cover how to use it, the algorithm underneath, and how the limit is shared between instances, with an example service and real outputs.
A service with plans#
This is the post's example service, in full. It has two plans, free and pro, three routes with different costs, and it keeps the limits in Redis:
// A service with plans. The API key decides the plan, Redis keeps
// the limits (every instance shares them) and each route has its
// cost. Usage: cargo run --example server -- <port>
use std::sync::Arc;
use axum::http::StatusCode;
use axum::{Router, routing::get};
use tower_rate_tier::{
LimitEvent, OnMissing, Quota, RateTier, RedisStorage, TierIdentity,
TierLimitLayer,
};
// In a real service, this would come from the database.
fn plan_of(api_key: &str) -> Option<&'static str> {
match api_key {
"key_ana" => Some("free"),
"key_bea" => Some("pro"),
"key_eva" => Some("gold"), // a plan the limiter doesn't know
_ => None,
}
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let port = std::env::args().nth(1).unwrap_or("3000".into());
let conn = redis::Client::open("redis://127.0.0.1:6379")?
.get_connection_manager()
.await?;
let tiers = RateTier::builder()
.tier("free", Quota::per_minute(10))
.tier("pro", Quota::per_minute(100))
.default_tier("free")
// No key, or a key that doesn't exist: 401.
.on_missing(OnMissing::Deny(StatusCode::UNAUTHORIZED))
.storage(Arc::new(RedisStorage::new(conn)))
.build();
let layer = TierLimitLayer::new(tiers)
.identifier_fn(|headers| {
let key = headers.get("x-api-key")?.to_str().ok()?;
Some(TierIdentity::new(key, plan_of(key)?))
})
.cost_fn(|req| match req.uri.path() {
"/report" => 5,
"/backup" => 50, // more than the free plan gives in a minute
_ => 1,
})
.on_event(|event| {
if let LimitEvent::UnknownTier { user_id, tier, .. } = event {
eprintln!("unknown tier {tier:?} for {user_id}");
}
});
let app = Router::new()
.route("/data", get(|| async { "data\n" }))
.route("/report", get(|| async { "report\n" }))
.route("/backup", get(|| async { "backup\n" }))
.layer(layer);
let addr = format!("127.0.0.1:{port}");
let listener = tokio::net::TcpListener::bind(addr).await?;
axum::serve(listener, app).await?;
Ok(())
}Piece by piece:
- Plans are declared with a name and a quota:
Quota::per_minute(10)means 10 requests per minute.default_tier("free")is the fallback plan for the cases we'll see further down. identifier_fnreceives the headers and returns who the user is and their plan, orNoneif it can't tell. Here the API key decides the plan; in a real service it would come from the database, and that's what theTierIdentifiertrait is for, since it's asynchronous.cost_fndecides what each request costs:/datauses 1 from the quota,/reportuses 5 and/backup, 50.on_eventreports what the limiter resolves on its own, such as an unknown plan. It's there for logs and metrics.
cost_fn runs inside the middleware, and that matters with Axum. The crate also has a tier_cost(n) layer, but if you put it on a route with .layer(...) while the limiter is added with Router::layer, the route's layer runs after the limiter: the cost arrives too late and is ignored. Up to 0.2, the README and the Axum example did exactly that, so every request cost 1 without anyone noticing. 0.3 fixes it with cost_fn.
GCRA: why not a fixed window#
The simplest way to limit is a fixed window: a counter per minute that goes back to zero when the minute changes. The trouble is right at that change. This program compares it with what tower-rate-tier does, with the same limit of 10 per minute and the same 20 requests: 10 at second 59 and another 10 at second 60.
// Fixed window versus GCRA, with the same limit: 10 per minute.
// 10 requests arrive at second 59 and another 10 at second 60.
use std::time::Duration;
use tower_rate_tier::clock::FakeClock;
use tower_rate_tier::{Quota, RateTier};
#[tokio::main]
async fn main() {
let arrivals = [(59, 10), (60, 10)];
// Fixed window: a counter per minute that resets when it changes.
let (mut minute, mut used, mut fixed) = (0, 0, 0);
for (t, count) in arrivals {
if t / 60 != minute {
(minute, used) = (t / 60, 0);
}
let ok = count.min(10 - used);
used += ok;
fixed += ok;
}
// GCRA, with tower-rate-tier and a fake clock.
let clock = FakeClock::new();
let limiter = RateTier::builder()
.clock(clock.clone())
.tier("free", Quota::per_minute(10))
.build();
let (mut now, mut gcra) = (0, 0);
for (t, count) in arrivals {
clock.advance(Duration::from_secs(t - now));
now = t;
for _ in 0..count {
if limiter.check("ana", "free", 1).await.unwrap().is_ok() {
gcra += 1;
}
}
}
println!("fixed window: {fixed} of 20 allowed in 2 seconds");
println!("GCRA: {gcra} of 20 allowed in 2 seconds");
}This is the real output, on Linux with Rust 1.94:
fixed window: 20 of 20 allowed in 2 seconds
GCRA: 10 of 20 allowed in 2 secondsWith the fixed window all 20 get through in two seconds, twice the limit, because the first 10 count towards one minute and the next 10 towards another. That's the burst at the window boundary.
tower-rate-tier uses GCRA (Generic Cell Rate Algorithm), an algorithm that comes from ATM networking. Instead of counting requests, it keeps a single number per user: the TAT (theoretical arrival time), the moment the user's bucket would be full again. With 10 requests per minute:
- each request moves the TAT 6 seconds into the future (60 / 10), multiplied by its cost;
- the request is allowed if, after moving it, the TAT is no more than 60 seconds ahead of now;
- if there's no stored TAT, or it's already in the past, it starts from now.
This is how it behaves, step by step, with a fake clock:
// GCRA step by step: 10 requests per minute, with a fake clock.
use std::time::Duration;
use tower_rate_tier::clock::FakeClock;
use tower_rate_tier::{Quota, RateTier};
#[tokio::main]
async fn main() {
let clock = FakeClock::new();
let limiter = RateTier::builder()
.clock(clock.clone())
.tier("free", Quota::per_minute(10))
.build();
// (seconds it waits, requests it sends afterwards)
let mut t = 0;
for (wait, count) in [(0, 11), (6, 2), (30, 6)] {
clock.advance(Duration::from_secs(wait));
t += wait;
for _ in 0..count {
match limiter.check("ana", "free", 1).await.unwrap() {
Ok(info) => {
let left = info.remaining;
println!("t={t:>2}s 200 remaining {left}")
}
Err(limited) => {
let wait = limited.retry_after_secs();
println!("t={t:>2}s 429 retry after {wait} s")
}
}
}
}
}This is the real output, on Linux with Rust 1.94:
t= 0s 200 remaining 9
t= 0s 200 remaining 8
t= 0s 200 remaining 7
t= 0s 200 remaining 6
t= 0s 200 remaining 5
t= 0s 200 remaining 4
t= 0s 200 remaining 3
t= 0s 200 remaining 2
t= 0s 200 remaining 1
t= 0s 200 remaining 0
t= 0s 429 retry after 6 s
t= 6s 200 remaining 0
t= 6s 429 retry after 6 s
t=36s 200 remaining 4
t=36s 200 remaining 3
t=36s 200 remaining 2
t=36s 200 remaining 1
t=36s 200 remaining 0
t=36s 429 retry after 6 sThe first 10 requests take the TAT from second 0 to 60. The eleventh would take it to 66, more than 60 seconds ahead, so it's rejected: it has to wait 6 seconds. At second 6 exactly one more fits, and the TAT moves to 66. At second 36 the TAT is still at 66, only 30 seconds ahead: that leaves 30 free seconds, and at 6 seconds per request that's 5 requests.
In other words, a user can spend the whole limit at once, but then the quota comes back little by little, at the plan's rate, rather than all at once when the minute changes.
GCRA keeps a single number per user, the moment their quota would be full again, and uses it to decide every request: no counters that reset and no bursts at the minute boundary.
The fake clock, FakeClock, is part of the crate. With it, tests don't depend on the real time and don't have to wait: they move the clock forward 6 seconds and check the result instantly, the same every time.
Several instances, one limit: Redis#
With the redis feature, RedisStorage keeps each user's TAT in Redis instead of in memory, so every instance shares the same limit. To check it, I started the service twice, on ports 3000 and 3001, against the same Redis, and Ana, on the free plan, alternates between them:
# Ana (free plan, 10 per minute) alternates between both instances.
for i in $(seq 1 11); do
port=$((3000 + i % 2))
curl -s -o /dev/null -w "$port %{http_code}\n" \
-H "x-api-key: key_ana" "localhost:$port/data"
doneThis is the real output, on Linux with Redis 7.0:
3001 200
3000 200
3001 200
3000 200
3001 200
3000 200
3001 200
3000 200
3001 200
3000 200
3001 429Ten requests allowed across both instances and the eleventh rejected: there's one limit, not one per instance. This is the full response to a rejection:
curl -si -H "x-api-key: key_ana" localhost:3000/dataThis is the real output, on Linux with Redis 7.0:
HTTP/1.1 429 Too Many Requests
content-type: application/json
retry-after: 6
x-ratelimit-limit: 10
x-ratelimit-remaining: 0
x-ratelimit-reset: 1790947155
content-length: 61
date: Fri, 02 Oct 2026 13:18:14 GMT
{"error":"rate limit exceeded","tier":"free","retry_after":6}Retry-After says how many seconds to wait, and the body repeats it in JSON. X-RateLimit-Reset is the Unix time at which the quota will be full again. Retry-After is rounded up. In 0.2 it was rounded down, and a client that waited exactly as long as it was told got another 429.
What's left in Redis? One key per user and plan:
# Ana's bucket key: the plan and the SHA-1 of the user id.
key="trt:free:$(printf key_ana | sha1sum | cut -c1-40)"
redis-cli --scan --pattern 'trt:*'
redis-cli PTTL "$key"This is the real output, on Linux with Redis 7.0:
trt:free:33d2315cbeb866b8b237240a98d605f2e6e41b8a
59841The key is trt:<plan>:<sha1(user)>, so the identifier isn't stored in the clear. If identifiers have little entropy, like IP addresses or emails, the SHA-1 can be reversed by trying values, and that's what .key_secret(secret) is for: it computes the key with HMAC-SHA1 and a secret. The second number is PTTL: the key expires in about 60 seconds, exactly when Ana's bucket is full again. There's nothing to clean up.
Every check is a Lua script that Redis runs atomically: while it runs, no other command touches the key, so two instances can't read the same TAT and both allow the last request. This is the last part of gcra.lua, where the decision is made:
-- A key of another type makes GET fail; pcall turns that into an error
-- table, which tonumber() reads as nil. Not an integer (this includes NaN)
-- means a corrupted value too: start fresh.
local stored = redis.pcall("GET", KEYS[1])
if type(stored) == "table" then
stored = nil
end
local tat = tonumber(stored)
local capped = false
if tat == nil or tat ~= math.floor(tat) or tat < now then
tat = now
elseif tat > now + burst_offset then
tat = now + burst_offset
capped = true
end
local increment = emission_interval * cost
if increment > MAX_EXACT - tat then
return fail("time values exceed the exact range of Lua numbers")
end
local new_tat = tat + increment
local allow_at = new_tat - burst_offset
if allow_at > now then
if capped then
redis.call("SET", KEYS[1], tat, "PX", math.ceil((tat - now) / 1000))
end
return { 0, 0, allow_at - now, tat - now }
end
if new_tat > now then
redis.call("SET", KEYS[1], new_tat, "PX", math.ceil((new_tat - now) / 1000))
end
local remaining = math.floor((burst_offset - (new_tat - now)) / emission_interval)
return { 1, remaining, 0, new_tat - now }The script is the same logic as the GCRA in Rust, with three details that only show up when you move it to Redis:
- The clock is Redis's. The script reads the time with
TIME, so it doesn't matter that the instances' clocks disagree. - The expiry is rounded up (
math.ceilin thePX). If it were rounded down, the key could vanish a millisecond early and give away requests. - If Redis's clock goes backwards (for example, on failover to a replica whose clock is behind), the TAT is capped at a full bucket and stored that way. Without that, the user would stay locked out for as long as the clock went back.
The script works in microseconds, not nanoseconds like the Rust side. Lua numbers are doubles, exact for integers up to 253: in microseconds since 1970 that reaches the year 2255; in nanoseconds it wouldn't even cover today's date.
The script is tested twice: in an embedded Lua 5.1, the same version Redis uses, with no server needed, and against a real Redis in CI. If Redis takes longer than 100 ms to answer, the check counts as a storage error, which I cover further down.
Requests that cost more#
Bea is on the pro plan, 100 per minute, and fetches some data and then a report:
# Bea (pro plan, 100 per minute): /data costs 1 and /report, 5.
for path in data report; do
curl -s -o /dev/null -H "x-api-key: key_bea" \
-w "/$path %{http_code} remaining %header{x-ratelimit-remaining}\n" \
"localhost:3000/$path"
doneThis is the real output, on Linux with Redis 7.0:
/data 200 remaining 99
/report 200 remaining 94/data uses 1 and leaves 99; /report uses 5 and leaves 94. For GCRA, a request costing 5 is like five requests at once: it moves the TAT 5 intervals in one go.
Safe defaults#
The trickiest part of a limiter isn't the algorithm, it's what it does when something doesn't fit. Eva has a valid key, but Eva's plan, gold, isn't configured:
# Eva has a plan the limiter doesn't know.
curl -s -o /dev/null -H "x-api-key: key_eva" \
-w "/data %{http_code} limit %header{x-ratelimit-limit}\n" \
localhost:3000/data
curl -s -o /dev/null -H "x-api-key: key_eva" \
-w "/backup %{http_code}\n" localhost:3000/backup
# No API key.
curl -s -o /dev/null -w "/data %{http_code}\n" localhost:3000/dataThis is the real output, on Linux with Redis 7.0:
/data 200 limit 10
/backup 403
/data 401And this is what the service wrote to standard error, from on_event:
unknown tier "gold" for key_eva
unknown tier "gold" for key_evaThree cases, three decisions:
- An unknown plan doesn't grant unlimited access. Eva gets the default plan's quota (
limit 10) in Eva's own bucket, andon_eventreports every request. An unknown plan might be a typo, a new plan the limiter doesn't know yet or, worse, a value the client controls. Up to 0.2, a request with an unknown plan went through with no limit at all; 0.3 fixes it and the changelog lists it as a security fix. If there's no default plan, the answer is403, andOnUnknownTiercan also chooseDenyor an explicitAllow. - A request that could never succeed doesn't get a 429.
/backupcosts 50 and thefreeplan gives 10 per minute: no amount of waiting would make it possible. So it answers403 Forbidden, with noRetry-Afterand without touching Redis. - Unidentified requests get an explicit decision. Here, with
OnMissing::Denyand theUNAUTHORIZEDstatus, a request with no key gets401. By default (OnMissing::UseDefault) it would get the default plan.
If Redis fails or takes longer than 100 ms, by default the request goes through (OnStorageError::Allow): better not to limit during an outage than to take the whole API down. If you prefer the opposite, OnStorageError::Deny answers 503. Either way, on_event receives a LimitEvent::StorageError, so a Redis outage doesn't go unnoticed.
What's next#
The 0.4 roadmap focuses on operations:
- changing plans on the fly, without restarting the service;
- Prometheus-compatible metrics;
- support for Tonic and gRPC;
- keeping the limit in local memory while Redis is down, and a circuit breaker so a down Redis doesn't cost every request its 100 ms timeout.
If any of these releases brings something worth telling, I'll tell it here.
What I take away#
- Limiting by plan is mostly about identifying well. The algorithm is the easy part; knowing who's asking and on which plan, and what to do when you don't know, is what decides whether the limit is any use.
- GCRA does a lot with very little. With a single number per user it spreads the quota at the plan's rate and even tells you how long to wait.
- With several instances, both the state and the clock have to be shared. An atomic script in Redis and Redis's own time solve both at once.
- Defaults are security decisions. An unknown plan, an unidentified request or a Redis outage need a deliberate answer, not whatever happens by accident.
- An injectable clock makes time testable. Tests don't wait for a minute to pass: they move the clock and check.
tower-rate-tier is a crate of mine, licensed under MIT or Apache 2.0. 0.1.0 came out on 11 March 2026 and 0.3.0 on 2 October 2026. Everything in this post is 0.3.0 as downloaded from crates.io: the example service and the outputs were run on Linux, with Rust 1.94 and Redis 7.0.
References
- tower-rate-tier on crates.iocrates.io · crates.io
- tower-rate-tier documentationdocs.rs · docs.rs
- tower-rate-tier: source codeGitHub · github.com
- tower-rate-tier: changelogGitHub · github.com
- tower-rate-tier: roadmapGitHub · github.com
- Generic cell rate algorithmWikipedia · en.wikipedia.org
- Scripting with LuaRedis · redis.io
- TIMERedis · redis.io
- RFC 6585: Additional HTTP Status Codes (429 Too Many Requests)IETF · rfc-editor.org
- RFC 9110: HTTP Semantics (Retry-After)IETF · rfc-editor.org
Share
Need Rust development?
Secure, high-performance software development with Rust for your business. Consulting, training, and custom projects.
Let's talk→
Comments
Commenting requires a GitHub account. Comments live in GitHub Discussions (SoftDryzz/blog-comments) and are moderated: no promotional links.