Rate Limiting de API para LLMs: Conte Tokens, Não Requisições

Por que requisições por minuto deixaram de funcionar

O rate limiting clássico de API supõe que as requisições sejam fungíveis: um GET /users/42 custa aproximadamente o mesmo que o próximo, então contar requisições é um bom indicador de carga. Todos os rate limiters que você já configurou foram construídos com base nisso.

O tráfego de LLMs quebra esse modelo. Mesmo endpoint, mesmo minuto, mesmo usuário: “resuma isto em uma linha” consome cerca de 50 tokens no ciclo completo; um contrato de 150 páginas enviado para um modelo de raciocínio chega perto de 200.000. Ambos representam uma única requisição, e um limite de 1.000 requisições por minuto permite qualquer um dos casos.

Essa variação é o comportamento normal do tráfego em produção quando agentes estão envolvidos, porque a interação de um agente carrega toda a conversa, os resultados das ferramentas e o contexto recuperado de volta para o prompt a cada passo. O número de requisições permanece estável enquanto a contagem de tokens sobe uma ordem de grandeza — o mecanismo por trás da explosão de tokens por agentes em CI/CD.

Portanto, mude a unidade. Conte tokens, porque tokens são o que você compra. A contagem de requisições ainda importa — ela protege o gateway e a conexão com o provedor —, portanto, execute ambos.

Quatro controles que as pessoas chamam de “rate limiting”

A maior parte da confusão aqui é uma questão de vocabulário. Quatro problemas, quatro mecanismos, e as equipes frequentemente implementam um acreditando ter implementado outro:

Rate limits são um controle de disponibilidade; orçamentos são um controle financeiro. Eles falham de maneiras diferentes e têm responsáveis diferentes — a plataforma responde pelo primeiro, as finanças pelo segundo.

O erro comum é instalar um rate limit de tokens e chamá-lo de controle de custos. 20.000 tokens por minuto em um modelo barato custam poucos dólares por dia; em um modelo de raciocínio de ponta, é um valor completamente diferente, que muda sempre que o provedor reajusta os preços. Vazão de tokens não é dinheiro.

Onde aplicar o controle

Os limites dos provedores merecem um alerta, pois as equipes costumam confiar neles sem perceber o risco. O limite da sua organização na OpenAI ou Anthropic é um único pool compartilhado: quando um job em lote o satura, seu produto voltado ao cliente é limitado por um sistema que não consegue identificar que “o assistente sempre tem prioridade”. Daí a importância de um gateway sob seu controle.

Janela fixa, janela deslizante e token bucket

O algoritmo decide quanto pico de tráfego consegue passar — um detalhe nada insignificante para agentes.

Para o tráfego de chat humano, a janela fixa funciona bem — as pessoas não se coordenam. Agentes sim, mesmo que acidentalmente. Eles tentam novamente após uma falha, realizam chamadas em paralelo e funcionam com horários agendados, fazendo com que múltiplos chamadores atinjam o mesmo instante no relógio, tornando o cenário de pico duplo algo real e não apenas teórico. As janelas deslizantes resolvem isso por não possuírem um momento de reinicialização. O token bucket responde a uma necessidade diferente — ele é ideal para tráfego onde você deseja permitir surtos curtos —, ao custo de ter mais um parâmetro para ajustar.

O que fazer quando um limite é atingido

O downgrade é o recurso menos utilizado: se um limite no nível do modelo é atingido, uma cadeia de fallback pode servir a resposta a partir de um segundo provedor em vez de retornar um erro 429 ao usuário — o mecanismo de failover descrito em nosso artigo sobre roteadores de LLM, onde o 429 atua como um código de disparo. O estouro de um orçamento é diferente: se o dinheiro acabou, ele acabou, e gastá-lo silenciosamente em um lugar mais barato não é o que a equipe financeira solicitou.

Onde as equipes erram

Regra genérica acima da específica. Sob a aplicação da regra da primeira correspondência (first-match-wins), uma regra ampla no topo absorve o tráfego que deveria ter correspondido a uma regra mais restrita abaixo dela. A regra restrita nunca é executada.

Tratar um contador compartilhado como um limite por usuário. “20.000 tokens por minuto” sem escopo definido é um único contador para todos. O primeiro chamador consome tudo.

Assumir que requisições com falha são gratuitas. Para limites baseados em requisições, elas não são — e para limites de tokens, o comportamento é diferente.

Quer ver a sua distribuição real de tokens antes de escolher um limite?

Roteie uma fração do tráfego através de um gateway e analise o histograma de tokens, não a contagem de requisições.

Comece gratuitamente

Como o TrueFoundry implementa isso

Dois objetos de política, deliberadamente separados: o rate limiting gerencia a vazão, os orçamentos gerenciam o dinheiro.

O enum de unidades

As regras de rate limit aceitam seis unidades — o conjunto completo:

requests_per_minute · requests_per_hour · requests_per_day · tokens_per_minute · tokens_per_hour · tokens_per_day

Não existe unidade por segundo; uma única requisição de LLM pode levar dezenas de segundos, portanto, limites por segundo mediriam apenas ruído. A configuração fica na aba Config:

Um conjunto de regras tem o tipo: gateway-rate-limiting-config com uma lista de regras. Cada regra possui um id estático, um bloco when cujas condições de subjects, models e metadata se combinam com AND, um valor inteiro limit_to, uma unidade e, opcionalmente, rate_limit_applies_per. Os assuntos (subjects) possuem prefixos — user:, team:, virtualaccount: — e os metadados leem o cabeçalho X-TFY-METADATA.

A janela deslizante, em detalhes

Como a unidade mínima é por minuto, o gateway mantém uma janela de 60 segundos, preserva buckets temporais a cada 10 segundos para cada usuário, modelo, equipe ou segmento personalizado e soma os últimos 6 buckets para avaliar o contador. Buckets mais antigos são descartados. A resolução de dez segundos é o ponto chave: um pico é suavizado ao longo de seis subintervalos em vez de ser permitido duas vezes na transição de um limite.

Definindo o escopo com rate_limit_applies_per

Sem esse parâmetro, uma regra funciona como um contador compartilhado para tudo o que ela corresponder. Com ele, o contador se divide por entidade. Os valores permitidos são user, virtualaccount, model e metadata.* com a sua própria chave. No máximo dois valores por regra.

['user'] concede a cada usuário a sua própria cota e ['model'] a cada modelo a sua. A última regra é o padrão que a maioria das equipes busca: um limite por projeto baseado em metadados que a aplicação já envia, sem a necessidade de editar regras quando um novo projeto surge.

Isso substituiu o formato dinâmico de rule-ID. A migração é direta — {user}-daily-limit torna-se id: 'user-daily-limit' acrescido de ['user'], e project-{metadata.project_id}-limit torna-se id: 'project-limit' acrescido de ['metadata.project_id']:

Aplicação e contabilização são coisas diferentes

Cada requisição é avaliada em relação a todas as regras, mas apenas a primeira regra correspondente é aplicada. Correspondências posteriores nunca bloqueiam a requisição. O uso, no entanto, é contabilizado em todas as regras que a requisição corresponder.

Por isso, mantenha as regras especializadas no topo. O caso de falha documentado: colocar app-a-limit (10.000 rpm, virtualaccount:app-a) acima de tenant-wide-limit (5.000 rpm, when: {}), fará com que o tráfego do app A — contabilizado em ambas — sature sozinho o contador do tenant. Todos os usuários cuja primeira correspondência for a regra do tenant receberão um erro 429 bem abaixo dos 5.000 rpm. A solução não é reordenar, mas sim definir o escopo: rate_limit_applies_per: ['user', 'virtualaccount'].

A regra de contabilização de falhas

Qualquer requisição rejeitada pelo gateway, ou em que o provedor falhar com um erro 4XX/5XX, conta como uma requisição em todas as regras requests_per_* com as quais correspondeu. Há uma exceção: uma requisição já rejeitada com um 429 pelo próprio rate limiting, garantindo que uma tempestade de re-tentativas não amplie o problema.

Limites de tokens se comportam de maneira diferente. Requisições com falha não consomem cota de tokens porque uma requisição que falhou não registra tokens. Não há o que contar. É por isso que um loop de re-tentativas pode esgotar o seu orçamento de requisições enquanto o painel de tokens continua parecendo saudável.

Uma violação retorna HTTP 429 com error.type: "RateLimitError" e error_origin_level: "rate_limit_budget", além do cabeçalho x-tfy-applied-rules indicando o nome da regra acionada.

Budget Limiting V2

Os orçamentos são o controle financeiro, e eles são exclusivamente de custo, cost_per_* em USD. Não existe orçamento denominado em tokens — se você precisa de um limite máximo de tokens, use o rate limit.

O Budget V2 foi lançado na v0.158.0 e inverte a lógica de aplicação: todas as regras correspondentes são checadas e todas devem autorizar a requisição, funcionando como um AND entre os orçamentos. O rate limiting opera pela regra da primeira correspondência; os orçamentos exigem que todas aprovem. A V1 utilizava a primeira correspondência, portanto a migração envolve uma mudança semântica, não de sintaxe.

As regras ficam em AI Gateway → Policies → Budget Limiting → Add Rule, em dois escopos: tenant (tenant-budget-config) ou team (team-budget-config, com um team_name validado por RBAC).

Cinco períodos de reinicialização, todos em UTC: Diário (00:00), Semanal (Segunda-feira 00:00), Mensal (dia 1º), Trimestral (1º de jan, 1º de abr, 1º de jul, 1º de out) e Vitalício (Lifetime), que nunca se reinicia — o limite de custo absoluto (spend cap) da tabela acima:

Uma única regra pode aplicar vários períodos simultaneamente, bloqueando o acesso se qualquer um for excedido — o exemplo da documentação para limite multi-período define cost_per_day: 0.5, cost_per_month: 0.5 e cost_per_quarter: 2 juntos. Os filtros de escopo — Subjects, Models, Provider accounts, Metadata — aceitam IN/NOT IN e se combinam com AND:

O parâmetro Apply limit as (applies_to.type) aceita aggregate, per-user, per-model, per-virtual-account ou metadata com uma chave, e não pode ser alterado após a criação. Regras por entidade suportam exceções (overrides) para usuários, modelos, contas virtuais ou valores de metadados específicos:

Uma exceção substitui todos os períodos para aquela entidade. Se a regra base define limites diários e trimestrais e a exceção define apenas um limite diário, essa entidade não terá limite trimestral. Inclua todos os períodos que deseja aplicar.

Três modos: enforce (padrão, rejeita), audit (permite o tráfego, rastreia e envia alertas) e soft_enforce — bloqueia apenas quando nenhum outro orçamento correspondente puder permitir a requisição; se outro tiver margem, a requisição passa e a violação é registrada como auditoria. Uma violação no modo hard enforce em qualquer regra sempre prevalece.

Os alertas são acionados a 75, 90, 95 e 100 por cento, cada um uma vez por período de orçamento, separadamente para cada entidade em um orçamento por entidade; orçamentos vitalícios alertam apenas uma vez por limite, para sempre. Destinos: email, slack-webhook, slack-bot, pagerduty, ms-teams-webhook, com suporte a {{user.email}} para envio individual por usuário.

Um detalhe importante: os contadores de orçamento começam no momento da criação da regra, não no início do período. O gasto anterior não é contabilizado retroativamente, portanto, uma regra criada no meio do mês não baterá com a sua fatura daquele período.

De onde vêm os números de custo

Os orçamentos são tão precisos quanto a precificação que os fundamenta, por isso essa precificação é pública. O repositório em github.com/truefoundry/models é a base de dados de preços utilizada para o acompanhamento público de custos, disponível para consulta em truefoundry.com/models. Verifique a taxa cobrada para o seu uso; envie um PR se encontrar alguma incorreção.

Dois detalhes são essenciais. Precificação por região: providers/aws-bedrock/us.amazon.nova-lite-v1:0.yaml contém taxas de entrada e saída diferentes para us-west-2, us-west-1, eu-central-1 e eu-west-1, garantindo que o tráfego multi-região não seja precificado incorretamente por uma taxa única. Precificação em faixas (tiered): providers/google-gemini/gemini-2.5-pro.yaml possui taxas base e taxas mais altas a partir de 200K tokens, e o gemini-1.5-flash.yaml aplica faixas a partir de 128K tokens. Contextos longos não têm custos lineares. Modelos sem precificação pública utilizam uma entrada de Private Cost.

Atribuição: direcionando orçamentos ao responsável correto

Um orçamento por usuário só funciona se as requisições forem atribuídas de forma confiável. Três mecanismos tornam essa atribuição automática, sem depender da disciplina dos desenvolvedores:

• Adicione tags às contas virtuais. As tags são injetadas automaticamente como metadados em todas as chamadas feitas com o token dessa conta; o serviço não precisa enviar nada além.
• Associe PATs a equipes. Um token vinculado a uma equipe carrega a tag da equipe automaticamente, e os administradores podem exigir a seleção da equipe para que um token não possa ser criado sem ela.
• Exija metadados com o guardrail Metadata Validation onde um campo for estritamente necessário.

O Model Metrics monitora Total Input Tokens, Total Output Tokens e Total Cost of Tokens em USD, exportáveis através de Metrics → 3 pontos → Download Raw Data agrupados por username, model_name ou teams:

Um exemplo prático

Um gateway, três grupos: um assistente voltado ao cliente, um agente interno de codificação e uma equipe de dados fazendo extração em massa, todos na mesma conta de provedor. O agente de codificação teve um pico atípico no mês passado e todos os outros usuários receberam erros 429.

Evite o esgotamento de recursos. O problema era um contador compartilhado, não a falta de um limite. Coloque uma regra coding-agent-tpm (200.000 tokens_per_minute, subjects: ["virtualaccount:coding-agent"]) acima de uma regra genérica tenant-wide (500.000 tokens_per_minute, when: {}), e aplique à regra genérica rate_limit_applies_per: ['virtualaccount'] para que o agente não esgoste a cota de todos ao corresponder a ambas. Adicione também uma regra de requests_per_minute para os mesmos subjects: requisições com falha contam para essa regra, mas não para a regra de tokens.

Defina o limite financeiro. Um orçamento mensal por usuário no agente de codificação com exceção para um engenheiro específico, além de um limite vitalício (Lifetime cap) no projeto de extração:

Ambos são verificados a cada requisição correspondente e ambos precisam aprovar a chamada. A exceção aumenta o limite de um engenheiro sem afrouxar o dos demais e, por substituir todos os períodos, ela reitera os limites da regra base.

Inicie no modo de auditoria para depois atribuir. Execute no mode: audit por uma semana: o uso é monitorado e os alertas são disparados, sem bloquear nada. Analise os alertas de 75%, ajuste os limites ao tráfego real e depois passe a aplicar (enforce). Adicione tags a cada conta virtual, exija a seleção de equipes nos PATs, e o relatório de cobrança interna estará pronto — o objetivo da atribuição de custos por equipe.

Pronto para definir um limite máximo?

Configure um rate limit de tokens e uma regra de orçamento, execute uma semana em auditoria e depois passe a aplicar os limites.

Comece gratuitamente

Pontos de atenção importantes

Os dois sistemas aplicam regras em direções opostas. O rate limiting funciona pela primeira correspondência (first-match-wins); exatamente uma regra bloqueia. O Budget V2 exige a aprovação de todas (all-must-pass); qualquer regra correspondente pode bloquear. Transferir a lógica de um modelo para o outro fará com que suas políticas produzam resultados inesperados.

Orçamentos não podem ser definidos em tokens, e rate limits não podem ser definidos em dólares. Você precisa de ambos. Além disso, a URL da documentação é /ai-gateway/ratelimiting, em uma única palavra — com hífen, retornará um erro 404.

O rastreamento de custos de áudio é mais restrito do que o de tokens. Ele cobre conversão de texto em fala e fala em texto na ElevenLabs e no Google Vertex; outros provedores de áudio registram o uso, mas não o custo por caractere ou por segundo, e a precificação de áudio privado está disponível apenas no Google Vertex. Serviços de fala em texto sem duração informada pelo provedor são contabilizados como custo zero — um orçamento permitirá tráfego ilimitado por considerá-lo gratuito.

Leituras relacionadas

• Rate Limiting em um Gateway de LLM
• Rate Limiting para Agentes de IA: Evitando o Esgotamento da API de LLMs
• Atribuição de Custos de LLM e Orçamentos por Equipe
• Solução para Rastreamento de Custos de LLM
• Observabilidade de Custos de IA

Conclusão

A transição de requisições para tokens requer pouca configuração e traz um grande impacto. Um contador de requisições indica o quão ocupado seu sistema está; um contador de tokens mostra o que você está comprando; um orçamento define o momento de parar.

Ajuste a estrutura em camadas corretamente e o restante se encaixa: limites de tokens suavizam o uso a cada minuto, limites de requisições protegem a infraestrutura, orçamentos gerenciam o mês e um limite vitalício (Lifetime cap) previne custos imprevistos. Os comportamentos descritos aqui correspondem à documentação do TrueFoundry de setembro de 2026.

Comece gratuitamente no TrueFoundry →