Rate Limiting

Rate limiting (Throttle)

Package: Carom.Extensions. A token bucket.

using Carom.Extensions;

var throttle = Throttle.ForService("external-api")
    .WithRate(100, TimeSpan.FromSeconds(1))
    .WithBurst(20)
    .Build();

var result = await CaromThrottleExtensions.ShotAsync(() => client.CallAsync(), throttle);

Defaults and rules

Setting	Default	Rule
WithRate(maxRequests, per)	100 per second	maxRequests at least 1, per positive
WithBurst	100	At least 1. The most tokens the bucket holds

Tokens refill with elapsed time. A call with no token available fails at once with ThrottledException (it carries ServiceKey, MaxRequests and TimeWindow) and CaromHooks.OnRateLimitRejected fires. Throttle never waits for a token.

The retry runs outside the throttle, and the default retry predicate skips ThrottledException, so a rejected call is not retried into the same limit. State is shared by service key, the same way as the circuit breaker.