Rate limiting em Minimal APIs com o middleware nativo do .NET

2026-11-02T12:12:03.214-03:00

Toda API exposta na internet, mais cedo ou mais tarde, recebe um cliente que resolve chamar o mesmo endpoint mil vezes por segundo. Pode ser um bug num loop de retry, um script mal escrito ou alguém testando a sorte. Se você não tem nenhum limite, quem paga a conta é o banco, o CPU e os outros usuários.

A boa notícia é que, desde o .NET 7, o rate limiting vem pronto no framework. Não precisa de pacote extra nem de biblioteca de terceiros. Neste post eu monto um exemplo pequeno com Minimal APIs, limite por IP, resposta 429 com Retry-After e testes de integração.

A ideia central

O middleware trabalha com dois conceitos: o limiter (o algoritmo: janela fixa, janela deslizante, token bucket ou concorrência) e a partição (quem está sendo limitado). Sem partição, o limite é global, e um cliente abusivo derruba o serviço para todo mundo. Particionando por IP, cada cliente tem o seu próprio balde.

Você registra uma policy com nome e depois aplica nos endpoints que precisam. Endpoints como health check normalmente ficam de fora, senão o orquestrador pode achar que a aplicação caiu.

Registrando a policy

builder.Services.AddRateLimiter(options =>
{
    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;

    options.AddPolicy("por-ip", context =>
        RateLimitPartition.GetFixedWindowLimiter(
            partitionKey: context.Connection.RemoteIpAddress?.ToString() ?? "anonimo",
            factory: _ => new FixedWindowRateLimiterOptions
            {
                PermitLimit = limit,
                Window = TimeSpan.FromSeconds(windowSeconds),
                QueueLimit = 0
            }));
});

O QueueLimit = 0 faz o excedente ser rejeitado na hora, em vez de ficar numa fila esperando a próxima janela. Para uma API pública isso costuma ser o que você quer. Os valores de limite e janela vêm da configuração, o que ajuda bastante na hora de testar.

Dizendo ao cliente quando voltar

Responder 429 sem dizer quando tentar de novo obriga o cliente a adivinhar, e adivinhação vira retry agressivo. O callback OnRejected permite devolver o cabeçalho Retry-After com o tempo restante da janela:

options.OnRejected = (context, _) =>
{
    if (context.Lease.TryGetMetadata(MetadataName.RetryAfter, out var retry))
    {
        context.HttpContext.Response.Headers.RetryAfter =
            ((int)retry.TotalSeconds).ToString();
    }
    return ValueTask.CompletedTask;
};

Aplicando nos endpoints

var app = builder.Build();

app.UseRateLimiter();

app.MapGet("/", () => Results.Ok(new { mensagem = "ola", hora = DateTime.UtcNow }))
   .RequireRateLimiting("por-ip");

app.MapGet("/health", () => Results.Ok("ok")); // sem limite

app.Run();

public partial class Program { }

Um detalhe que pega muita gente: UseRateLimiter() precisa vir antes do mapeamento dos endpoints que usam a policy, e o partial class Program no final existe só para o projeto de testes conseguir enxergar a classe.

Testando de verdade

Com WebApplicationFactory dá para subir a aplicação em memória e sobrescrever a configuração. Eu baixo o limite para 3 requisições e deixo a janela longa, assim o teste não depende de timing:

[Fact]
public async Task Requisicao_acima_do_limite_retorna_429_com_retry_after()
{
    var client = _factory.CreateClient();

    for (var i = 0; i < 3; i++) await client.GetAsync("/");
    var resp = await client.GetAsync("/");

    Assert.Equal(HttpStatusCode.TooManyRequests, resp.StatusCode);
    Assert.True(resp.Headers.Contains("Retry-After"));
}

Tem também um teste garantindo que o /health aguenta dez chamadas seguidas sem tomar 429. É o tipo de regressão que passa batido até o dia em que o load balancer tira sua aplicação do ar.

Rodando com Docker

O projeto tem um Dockerfile multi-stage com dois alvos, app e tests, e o compose expõe os dois:

docker compose up --build
# em outro terminal, chame mais de 5 vezes em 10 segundos
for i in $(seq 1 7); do curl -s -o /dev/null -w "%{http_code} " localhost:8080/; done

docker compose run --rm tests

Você deve ver algo como 200 200 200 200 200 429 429. Se olhar os cabeçalhos da resposta rejeitada, o Retry-After estará lá.

Cuidados antes de ir para produção

Esse limiter vive na memória de cada instância. Com várias réplicas atrás de um load balancer, cada uma conta por conta própria, então o limite efetivo é multiplicado pelo número de instâncias. Se você precisa de um limite global e exato, o caminho é um contador compartilhado, em geral no Redis, ou delegar isso ao gateway.

Atrás de proxy reverso, o RemoteIpAddress será o IP do proxy, não do cliente. Configure o ForwardedHeaders antes, senão todos os usuários caem na mesma partição e dividem o mesmo limite.

Para o dia a dia, o middleware nativo resolve bem a maioria dos casos de proteção básica, sem dependência nenhuma.

O código completo está em programero-csharp/2026-11-rate-limiting-minimal-apis.

PROGRAMERO