Guides

Adaptive rate limiting

A static rate limit is a guess made once, at config time, about traffic that changes every day. AdaptiveLimiter wraps the configured limiter and auto-tunes the effective policy from the same success/failure signal the circuit breaker already observes — no ML, no external model, just the same AIMD shape TCP congestion control has used for decades: additive growth on healthy traffic, multiplicative cut when errors rise.

Turn it on

rg := rateguard.New(rateguard.Config{
    Preset:            "llm-heavy",
    AdaptiveRateLimit:  true,
    Adaptive: rateguard.AdaptiveOptions{
        TargetErrorRate: 0.05, // default
        MinFactor:       0.25, // floor: 25% of configured policy
        MaxFactor:       2.0,  // ceiling: 200% of configured policy
    },
})

The policy stays the anchor

Adaptation scales your configured preset within [MinFactor, MaxFactor] — it never replaces it. Turn it off and the effective limit snaps back to exactly what you configured. Peek scales identically to Allow, so agent pre-flight answers stay honest while the limit is being adjusted.

How the controller decides

Every request outcome (success = HTTP status < 500) updates an exponential moving average of the error rate. Once per AdjustInterval (default 1s), the controller compares that EMA against TargetErrorRate:

Condition	Action
Error EMA ≥ 80% of target	Cut the effective limit multiplicatively (`factor × DecreaseFactor`, default 0.5) — before the error rate actually breaches the target, so the limiter sheds load before the circuit breaker would have to trip.
Error EMA below the trigger	Grow the effective limit additively (`factor + IncreaseStep`, default 0.05 per interval).

This predictive 80% trigger is deliberate: reacting only once the breaker's own threshold is breached means the breaker and the limiter fight the same fire at the same time. Cutting earlier gives the limiter first crack at recovery.

All options

Field	Default	Meaning
MinFactor	0.25	Floor — the effective limit never drops below 25% of the configured policy.
MaxFactor	2.0	Ceiling — the effective limit never exceeds 200% of the configured policy.
TargetErrorRate	0.05	The error rate the controller steers under.
IncreaseStep	0.05	Additive factor gain per healthy interval.
DecreaseFactor	0.5	Multiplicative cut applied on breach.
AdjustInterval	1s	Minimum time between controller decisions — rate-limits the rate limiter's own adjustments.
EMAAlpha	0.2	Weight given to each new outcome sample in the error-rate moving average.