Rate Limiting in .NET: Count Where the Other Side Counts
By Sergey Nosov
22 November 2026
My article on Chesterton’s Fence traced a puzzling line of code back to its reason. Every lookup in a batch waited 1,100 milliseconds before it called a vendor. The commit message explained why: the vendor allows one call per second per key, and 1,100 milliseconds leaves a margin. That article was about finding the reason before you take a fence down. This one is about building a better fence once you know it.
A delay paces one loop. It cannot see a second loop that uses the same key, and the vendor counts per key. The cure is to count where the other side counts. For the calls you make, that means one limiter shared by every caller, an algorithm that matches the vendor’s, and, once the app runs on several machines, one place that holds the count. For the calls you receive, it means a count for each caller and an answer that says when to come back.
I ran every example on .NET 11 (SDK 11.0.100) in November 2026. The vendor is a stand-in, as it was in the earlier article. It rejects any call that arrives less than a second after the last call it accepted, with 429 Too Many Requests, and each call simulates 100 milliseconds of work.
A Delay Paces One Loop
Here is the delay, rebuilt in C#:
static async Task LookupAllAsync(
IVendor vendor, string[] ids)
{
foreach (var id in ids)
{
await Task.Delay(1100);
await vendor.LookupAsync(id);
}
}
On its own, the loop is polite: its calls are at least 1.1 seconds apart. Now run two batches of three lookups at the same time, a1 to a3 and b1 to b3. This is what the vendor saw, with each call’s time from the start of the run:
1111 ms a1 200 OK
1111 ms b1 429 Too Many Requests
2324 ms a2 200 OK
2324 ms b2 429 Too Many Requests
3542 ms a3 200 OK
3542 ms b3 429 Too Many Requests
Each pair of calls lands in the same millisecond, and one call of each pair is rejected. Neither loop does anything wrong. The count is in the wrong place: each loop counts its own calls, and the vendor counts the key’s.
HTTP does not tell you where the other side counts. RFC 6585, which defined the 429 status code in April 2012, says so: “Note that this specification does not define how the origin server identifies the user, nor how it counts requests.” A server, it goes on, can count “on a per-resource basis, across the entire server, or even among a set of servers.” The rule lives in the vendor’s documentation, and the fence has to match it. Here, that means one count for the whole key.
Four Ways to Count
Since version 7, .NET has shipped four limiters in the System.Threading.RateLimiting package, which Microsoft announced on 13 July 2022. An ASP.NET Core app already has them, because the ASP.NET Core shared framework includes the assembly. A console app or a worker service references the package from NuGet, where version 11.0.0 was published on 10 November 2026.
- Fixed window (
FixedWindowRateLimiter): so many permits per window, all returned when the window resets on a timer. A burst at the end of one window and another at the start of the next can arrive almost together. - Sliding window (
SlidingWindowRateLimiter): the window is cut into segments and moves one segment at a time. A permit comes back only when the segment it was taken in leaves the window, which smooths that edge. - Token bucket (
TokenBucketRateLimiter): a bucket of tokens, refilled at a steady rate, and each call takes one. Callers get a burst up to the size of the bucket, then the average rate. - Concurrency (
ConcurrencyLimiter): so many calls in flight at once, however long each takes. A permit comes back when the caller disposes of its lease. It limits load, not rate.
The Rate Limiting entry in my Software Development Principles series describes more algorithms than these, the leaky bucket among them. These are the four that .NET ships.
The choice matters. When I first put a token bucket in front of the vendor, with one token refilled every 1,100 milliseconds, I tested a quiet stretch: one call, a pause, then two calls at once. The second call has to wait for a token, and a TokenBucketRateLimiter you create yourself does not time its refills from your last call. It refills on a timer that starts when the limiter is created, and the bucket starts full. After a quiet stretch, the next refill can be a whole period away or almost due.
I ran that test seventeen times, each in a fresh process, with quiet stretches from 2.5 to 4.1 seconds. The token bucket started the two calls between 88 and 1,070 milliseconds apart, and the vendor rejected the second call in sixteen runs. A fixed window of 1,100 milliseconds fared no better, and for a similar reason: it resets on a timer, not from the last call. A sliding window of 1,200 milliseconds in twelve segments, the one in the next section, started them between 1,134 and 1,286 milliseconds apart, and the vendor rejected none.
A token bucket and a fixed window cap how many calls a period allows; neither promises a minimum spacing. A continuously refilled bucket of one token would make the second call wait a whole period, but .NET’s adds whole tokens on a fixed tick. A comment in the runtime’s source says it trusts “the timer to be close enough.”
My stand-in vendor measures the spacing between calls, so two calls that close together break its rule. A real vendor may count differently, which is the point: read how it counts, then pick the limiter that counts the same way. The sliding window spaced the calls here only because it allows a single permit; with ten permits, it would let ten calls through back to back. On your own API, where a burst is often welcome, the token bucket is a good fit, as the server below shows.
One Limiter for the Whole Process
Here is the fence rebuilt around a sliding window:
public sealed class VendorClient(IVendor vendor)
{
// Vendor docs: one call per
// second per key. One window
// for the whole process, in
// 100 ms slices: a permit
// comes back about 1,100 to
// 1,200 ms after its call.
static readonly RateLimiter Limit =
new SlidingWindowRateLimiter(
new SlidingWindowRateLimiterOptions
{
PermitLimit = 1,
Window = TimeSpan.FromMilliseconds(1200),
SegmentsPerWindow = 12,
QueueLimit = 100,
});
public async Task<string> LookupAsync(
string id, CancellationToken ct = default)
{
using RateLimitLease lease =
await Limit.AcquireAsync(1, ct);
if (!lease.IsAcquired)
throw new InvalidOperationException(
"Too many lookups waiting.");
return await vendor.LookupAsync(id, ct);
}
}
The limiter is static, so every caller in the process shares one count, however many VendorClient objects exist. That fits one vendor key; with several keys, keep one limiter per key. In an app built on dependency injection, a singleton limiter does the same job.
The numbers carry the margin. Twelve segments of 100 milliseconds make a window of 1,200 milliseconds. A permit taken during a segment comes back when that segment leaves the window, 1,100 to 1,200 milliseconds after the call, give or take the timer, even after a quiet stretch. The vendor sees arrivals, not permits, and scheduling and network delays can bring two calls closer on the way. The margin is there for that.
A window of 1,100 milliseconds in eleven segments would keep the steady pace at 1.1 seconds. But in seventeen quiet-stretch runs, it started two calls as little as 1,028 milliseconds apart, and most of the margin was gone.
The comment is the sign on the fence: the vendor’s limit, where it comes from, and what the numbers do.
Each call waits for a permit, and the line has two bounds. The queue limit lets up to 100 calls wait, about two minutes at 1.2 seconds each; past that, a call fails at once instead of piling up. The cancellation token lets each caller stop waiting, and a token with a deadline bounds the wait. In a test with three lookups at once, the third caller’s token was set to cancel after 300 milliseconds, and the caller left the line. The second went ahead at 1.2 seconds, and the vendor saw two calls.
The using statement disposes of the lease. For a concurrency limiter, that is what returns the permit. For the window limiters and the token bucket, permits come back with time, and disposing of the lease changes nothing.
Here are the same two batches through this client:
4 ms a1 200 OK
1210 ms b1 200 OK
2411 ms a2 200 OK
3609 ms b2 200 OK
4810 ms a3 200 OK
6011 ms b3 200 OK
The calls alternate between the batches, about 1.2 seconds apart, and every one comes back 200 OK. That is a little slower than the vendor allows, on purpose. The difference is the margin.
If your calls go through HttpClient, the limiter can sit in a DelegatingHandler instead, as Microsoft’s announcement showed. Share one limiter among the handlers, because IHttpClientFactory builds new ones after two minutes by default. Place it inside any retry handler, so that every attempt takes a permit.
Do not rely on the standard resilience handler to pace you, though. Its outermost strategy is called a rate limiter, but Microsoft’s documentation says it “limits the maximum number of concurrent requests being sent to the dependency,” with a default of 1,000 and no queue. A cap on concurrent requests does not pace calls to one a second.
Say “Not Yet,” and When to Come Back
Now the other side: your own API, in ASP.NET Core. The rate-limiting middleware answers a rejected request with 503 Service Unavailable unless you say otherwise; the API reference says RejectionStatusCode “Defaults to Status503ServiceUnavailable.” RFC 9110 says a 503 means that the server is “currently unable to handle the request due to a temporary overload or scheduled maintenance.” A caller over its limit is a different case: the server is fine, and the honest answer is 429. My article on the Backpressure-First Principle covers the difference in depth.
builder.Services.AddRateLimiter(o =>
{
// Over the limit: 429, not the
// default 503.
o.RejectionStatusCode = StatusCodes
.Status429TooManyRequests;
// A burst of two, then one a
// second. No queue: over the
// limit, answer at once.
o.AddTokenBucketLimiter("lookups", bucket =>
{
bucket.TokenLimit = 2;
bucket.TokensPerPeriod = 1;
bucket.ReplenishmentPeriod =
TimeSpan.FromSeconds(1);
bucket.QueueLimit = 0;
});
// Say when to come back, in
// whole seconds, rounded up,
// and never zero.
o.OnRejected = (context, _) =>
{
if (context.Lease.TryGetMetadata(
MetadataName.RetryAfter, out TimeSpan wait))
{
int seconds = (int)Math.Ceiling(
wait.TotalSeconds);
var response = context.HttpContext.Response;
response.Headers.RetryAfter =
Math.Max(seconds, 1).ToString();
}
return ValueTask.CompletedTask;
};
});
Without UseRateLimiter, the policy silently does nothing. The middleware goes into the pipeline, and the endpoint opts in by name:
app.UseRateLimiter();
app.MapGet("/lookup/{id}", (string id) => id)
.RequireRateLimiting("lookups");
Three settings do the work. The token bucket is set for a burst of two requests, then one a second. A queue limit of zero answers at once instead of holding the request. And OnRejected reads how long the limiter says to wait and sends it as Retry-After. RFC 9110 defines that header as “how long the user agent ought to wait before making a follow-up request,” in seconds or as a date. Here are three requests in a row:
$ curl -s -o /dev/null -D - \
"localhost:5103/lookup/[1-3]" \
| grep -E "^(HTTP|Retry-After)"
HTTP/1.1 200 OK
HTTP/1.1 200 OK
HTTP/1.1 429 Too Many Requests
Retry-After: 1
Two get 200 OK, and the third gets 429 with Retry-After: 1. Without the status-code line and OnRejected, the same app answered the third request with 503 and no Retry-After at all.
ASP.NET Core gives this bucket no timer of its own. The middleware’s documentation says AddTokenBucketLimiter replenishes its buckets “from a single shared timer.” In the runtime’s source, that timer runs every 100 milliseconds. It tops a bucket up by the time since its last top-up, but it skips a full bucket without resetting that time. So a bucket that sat full for a few seconds refills completely at the first tick after it empties.
In my runs, after the bucket had sat full for 3, 5, or 8 seconds, four requests got 200 within a quarter of a second, not two. After about twelve seconds, it was two again, which matches the source: the shared timer discards a bucket that has been idle for more than ten seconds. Test the burst you actually get, not only the one you configured.
Round the wait up, and never send zero. The header counts whole seconds, and a cast to int truncates, so half a second would go out as zero, an invitation to retry at once. On .NET 11, a window limiter can itself report zero, between the end of a window and its reset. Microsoft’s main OnRejected example rounds up with Math.Ceiling; another example on the same page casts.
The number itself is only as good as the limiter’s estimate, and that differs by limiter and by version:
- Token bucket: it reports a whole number of refill periods, here one, rather than the time until a token is back. In twenty-four trials against the server above, each after a three-second pause, the first success came 46 to 1,110 milliseconds after a 429 that said one second. Twenty-three came within 200 milliseconds, consistent with the shared timer above, and one came more than a second later.
- Fixed and sliding windows: on .NET 11, they estimate when the window resets or enough permits come back, ignoring callers already queued. On .NET 10, the sliding window reports nothing, so the same
OnRejectedsends 429 withoutRetry-After, and the fixed window reports whole windows. The release notes for .NET 11 Preview 4 and RC 1 list the changes; Microsoft’s pages on what is new in .NET 11 do not. I confirmed both with a probe against versions 10.0.15 and 11.0.0 of the package and through this middleware on .NET 10 and .NET 11. - Concurrency: it reports nothing, because it cannot know when a call will finish.
A client that honors Retry-After, as my article on retries that fail better recommends, now has a number to wait for. It should treat that number as a hint: wait at least that long, and still back off if the next answer is another 429.
An IETF draft would let servers say more. “RateLimit Header Fields for HTTP” defines headers “for servers to advertise their quota policies and the current service limits, thereby allowing clients to shape their requests to avoid exceeding server-imposed limits.” In other words, the server would tell the client how it counts. The draft’s twelfth revision appeared on 20 November 2026, and it is still a working-group draft, not a standard.
One Bucket per Caller
The server above shares one bucket among all its callers, so one busy caller can use up the requests meant for all of them. In production, give each caller a bucket of its own. ASP.NET Core calls this partitioning:
// One bucket per signed-in user.
o.AddPolicy("per-user", context =>
{
string? name =
context.User.Identity?.Name;
string key = name is null
? "anonymous" : "user:" + name;
return RateLimitPartition
.GetTokenBucketLimiter(key, _ =>
new TokenBucketRateLimiterOptions
{
TokenLimit = 2,
TokensPerPeriod = 1,
ReplenishmentPeriod =
TimeSpan.FromSeconds(1),
});
});
I tested it with two users signed in through JWT bearer tokens, on an endpoint that asks for the policy with RequireRateLimiting("per-user"). The first user’s third request in a row got 429, and the second user’s first request still got 200. Order matters: UseRateLimiter goes after UseRouting and UseAuthentication. Before authentication, every caller looks anonymous to the partition. My article on the backend-for-frontend pattern uses the same kind of partition, keyed by the session.
Key the partition by who the caller is once signed in, never by a value the caller can change. A user name is fine for a demo; in production, use a stable, unique identifier from the validated token, such as its subject claim. A caller who controls the key gets a fresh bucket whenever it changes the value, and every key costs memory. A comment in Microsoft’s own example warns that “partitioning on unbounded user-controlled input can exhaust memory (a DoS risk).”
The client’s IP address is a weak key too. The same documentation warns that partitions by client IP address leave an app “vulnerable to Denial of Service attacks that use IP Source Address Spoofing.” And many users behind one proxy share an address.
On an endpoint that allows anonymous calls, all anonymous callers share one bucket, and so does any signed-in caller without a name claim. A flood of them cannot drain a named user’s bucket, but it can lock out the rest of them. The user: prefix keeps a user who happens to be named anonymous out of that shared bucket. In a test, three anonymous calls in a row got 200, 200, and 429, and a user named anonymous still got 200.
Per-user budgets buy fairness, not a cap on total load, and rate limiting alone does not stop a flood from many machines. Microsoft says it can help against denial of service, but “it’s not a comprehensive solution for Distributed Denial of Service (DDoS) attacks.” That protection belongs to the platform in front of the app.
Where the Count Lives
A limiter in your code counts for one process. Microsoft’s documentation for the middleware says so plainly: it “keeps its counters in memory in each app instance,” and “the effective limit is the configured limit multiplied by the number of instances.” The client side works the same way. To stand in for two instances of the app, I gave each batch a limiter of its own:
2 ms a1 200 OK
5 ms b1 429 Too Many Requests
1212 ms a2 200 OK
1212 ms b2 429 Too Many Requests
2402 ms b3 200 OK
2402 ms a3 429 Too Many Requests
Each limiter paced its own batch, and the vendor again rejected one call of every pair. When the limit belongs to a shared key, count in one place:
- One owner. A single worker owns the key, and everything else hands it work through a queue.
- A shared store. Every instance takes its permits from one counter they can all reach. Microsoft suggests a custom rate limiter that “stores its counters in a shared store.”
- A gateway. The calls pass through one layer that counts for everyone.
On Azure, API Management can be that gateway, in every tier but Consumption. Its rate-limit-by-key policy answers 429 Too Many Requests once a key goes over its rate, with a Retry-After header by default. Even there, the count has edges. The policy’s documentation says it “tracks calls independently at each gateway where it is applied,” including each region of a multi-region deployment.
The algorithm depends on the tier, too. Microsoft’s guide to advanced request throttling says that “Classic tiers use a sliding window algorithm.” The v2 tiers use a token bucket instead, which lets a caller spend its whole limit in one initial burst. And Microsoft cautions that “rate limiting is never completely accurate.”
So pace below the limit, and handle the 429 anyway. A gateway’s count can differ from its configured limit, and the vendor’s count is the one that decides.
Azure Counts You Too
Azure’s own services limit their callers, and each counts in its own way:
- Cosmos DB for NoSQL counts request units, not requests: “In a given second, if the operations consume more than the provisioned request units, Azure Cosmos DB returns a 429 exception.” The wait arrives in a header of its own,
x-ms-retry-after-ms, in milliseconds. Microsoft says the Cosmos DB SDKs retry 429 automatically, “typically up to nine times.” It calls 1 to 5 percent of requests answered with 429 a healthy sign in a production workload, as long as latency is acceptable and the partitions are evenly loaded. - Azure Resource Manager has used a token bucket for each region since 2024. For reads in a subscription, each service principal’s bucket holds 250 tokens by default and refills at 25 a second. Its 429 “includes a Retry-After value,” and a request sent before that time is up is not processed; it gets a new value instead.
- Microsoft Graph answers 429, and its documented services send
Retry-After“except where indicated.” Microsoft says its SDKs “already implement handlers that rely on the Retry-After header,” but they do not retry requests inside a JSON batch. Retrying early only prolongs the wait, because Graph “continues to log resource usage while a client is being throttled.”
By default, the Azure SDK client libraries for .NET that are built on Azure.Core treat 429 as worth retrying. They also wait at least as long as Retry-After asks; I checked both in the Azure.Core source. So do not wrap another retry loop around these clients. My article on retries shows how loops multiply across layers. Tune the client’s own retry options instead, and handle the 429 that still gets through.
A Checklist for Rate Limits
- Find out how the other side counts: per key, per user, or per region, and in requests or in request units. HTTP does not say, so read the documentation.
- Count once for the whole key. Use one limiter for every caller in the process, and write the reason beside it.
- Match the algorithm to the counter. Test what happens after a quiet stretch; a token bucket or a fixed window can let two calls through almost together.
- Bound the line. Set a queue limit, and pass a cancellation token with a deadline.
- Answer 429, not 503, with
Retry-Afterrounded up and never zero. Check what your version of .NET reports for your limiter, and test the burst your server really allows. - Give each caller a bucket, keyed by a stable identity once signed in.
- Count in one place once you scale out. Pace below the limit, handle the 429 anyway, and do not wrap a second retry loop around an SDK that already retries the same request.
A question to take to your own project: Where does it meet a limit, one it calls into or one it enforces? And is the reason written down beside it?
Further Reading
- RFC 6585: Additional HTTP Status Codes (IETF, April 2012)
- RFC 9110: HTTP Semantics (IETF, June 2022), section 10.2.3 on
Retry-After - Announcing Rate Limiting for .NET (Brennan Conroy, 13 July 2022)
- Rate Limiting Middleware in ASP.NET Core (Microsoft Learn)
- Limit Call Rate by Key and Advanced Request Throttling with Azure API Management (Microsoft Learn)
- RateLimit Header Fields for HTTP (IETF draft, 20 November 2026)
- The Backpressure-First Principle: Accept Only What You Can Finish (on this site, 16 October 2026)
- Retries That Fail Better: Backoff, Budgets, and Dead Letters (on this site, 16 October 2026)