{"record":{"id":"9bc0410d159788e7","repo":"dotnet/yarp","slug":"rate-wait-count-count-exceeds-limiter-s-burst","errorCode":null,"errorMessage":"rate: Wait(count={count}) exceeds limiter's burst {burst}","messagePattern":"rate: Wait\\(count=(.+?)\\) exceeds limiter's burst (.+?)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"src/Kubernetes.Controller/Rate/Limiter.cs","lineNumber":156,"sourceCode":"    /// </summary>\n    /// <param name=\"count\">The count.</param>\n    /// <param name=\"cancellationToken\">The cancellation token that can be used by other objects or threads to receive notice of cancellation.</param>\n    /// <exception cref=\"Exception\">rate: Wait(count={count}) exceeds limiter's burst {burst}.</exception>\n    /// <returns>A <see cref=\"Task\"/> representing the asynchronous operation.</returns>\n    public async Task WaitAsync(int count, CancellationToken cancellationToken)\n    {\n        // https://github.com/golang/time/blob/master/rate/rate.go#L226\n        int burst = default;\n        Limit limit = default;\n        lock (_sync)\n        {\n            burst = _burst;\n            limit = _limit;\n        }\n\n        if (count > burst && limit != Limit.Max)\n        {\n            throw new Exception($\"rate: Wait(count={count}) exceeds limiter's burst {burst}\");\n        }\n\n        // Check if ctx is already cancelled\n        cancellationToken.ThrowIfCancellationRequested();\n\n        // Determine wait limit\n        var waitLimit = limit.DurationFromTokens(count);\n\n        while (true)\n        {\n            var now = _timeProvider.GetUtcNow();\n            var r = ReserveImpl(now, count, waitLimit);\n            if (r.Ok)\n            {\n                var delay = r.DelayFrom(now);\n                if (delay > TimeSpan.Zero)\n                {\n                    await Task.Delay(delay, cancellationToken).ConfigureAwait(false);","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/dotnet/yarp/blob/bd11867bee7df522e7fd3effb08a9c85fd616908/src/Kubernetes.Controller/Rate/Limiter.cs#L138-L174","documentation":"Thrown by the rate Limiter (a Go-style time/rate port) when WaitAsync is called with a count larger than the limiter's configured burst capacity, and the limit is not Limit.Max (unlimited). This mirrors Go's rate limiter semantics: a single reservation larger than burst can never be satisfied and is rejected immediately rather than blocking forever.","triggerScenarios":"Calling limiter.WaitAsync(count, ct) where count exceeds the burst value passed to the Limiter constructor. The check fails fast because no amount of waiting can accumulate enough tokens past the burst ceiling.","commonSituations":"Passing a batch size larger than the configured burst. Raising a batch count without proportionally raising burst. Default burst too small for the workload's reservation size.","solutions":["Reduce the count argument to be within the configured burst capacity.","Increase the burst parameter when constructing the Limiter (e.g., new Limiter(limit, burst: largerValue)).","If large batches are expected, use Limit.Max for an uncapped limiter or split the wait into smaller counts.","Check ReserveN().OK() before waiting to detect the over-burst condition without throwing."],"exampleFix":"// before\nvar limiter = new Limiter(Limit.PerSecond(10), burst: 5);\nawait limiter.WaitAsync(count: 8, ct); // throws\n// after\nvar limiter = new Limiter(Limit.PerSecond(10), burst: 10);\nawait limiter.WaitAsync(count: 8, ct);","handlingStrategy":"validation","validationCode":"if (count > burst && limit != Limit.Max)\n{\n    throw new ArgumentOutOfRangeException(nameof(count), $\"count {count} exceeds burst {burst}\");\n}\nawait limiter.WaitAsync(count, ct);","typeGuard":"static bool IsWithinBurst(Limiter lim, int count) => count <= lim.Burst;","tryCatchPattern":"try { await limiter.WaitAsync(count, ct); }\ncatch (Exception ex) when (ex.Message.Contains(\"exceeds limiter's burst\"))\n{ /* reduce count or increase burst, then retry */ }","preventionTips":["Pre-check count against burst before calling WaitAsync.","Use ReserveN().OK() to test feasibility without throwing.","Scale burst with batch size in configuration."],"tags":["rate-limiting","kubernetes","throttling","burst","validation"],"backgroundTag":null,"analyzedSha":"bd11867bee7df522e7fd3effb08a9c85fd616908","analyzedAt":"2026-08-13T21:29:49.359Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}