> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Rate limits e cotas > Entenda como o AI Gateway aplica rate limits baseados no plano, limites de orçamento e cotas dos provedores, e como interpretar respostas e headers 429. O **Toqan Router** aplica limites em três camadas. Toda solicitação ao **AI Gateway** passa por um rate limit da plataforma baseado no plano, por quaisquer limites de **Budget** que correspondam à solicitação e, por fim, pelas cotas do próprio provedor upstream. Saber qual camada rejeitou uma solicitação é o primeiro passo para corrigir o problema. | Camada | Aplicada por | Configurável | Aplica-se a | | - | - | - | - | | Rate limits da plataforma | **Toqan Router**, conforme o plano do workspace | Planos Enterprise, mediante acordo | Todas as solicitações ao gateway | | Limites de orçamento | **Toqan Router**, a partir dos budgets configurados | Sim, em **Settings > Organization > [Budgets](/docs/pt-BR/ai-gateway/budgets.md)** | Solicitações que correspondem ao escopo do budget | | Rate limits do provedor | A conta do provedor upstream | Pelo provedor | Solicitações roteadas para esse provedor | ## Rate limits da plataforma Cada workspace é limitado a um número fixo de solicitações por minuto, de acordo com a assinatura. Quando o limite é atingido, as solicitações são rejeitadas com `429 Too Many Requests` até que a janela de 60 segundos seja reiniciada. | Plano | Solicitações por minuto | | - | - | | Free (Pay as you go sem forma de pagamento cadastrada) | 20, e 50 por dia | | Pay as you go | 100 | | Enterprise | 1500, mais mediante acordo | * Os limites usam uma **janela fixa de 60 segundos** que começa com a primeira solicitação, a mesma janela usada nos limites de solicitações por minuto dos budgets. * Solicitações roteadas por uma chave de integração de provedor ou para um modelo privado contam para esses limites como qualquer outra solicitação. Consulte Faturamento BYOK. * Planos Enterprise podem negociar limites por minuto maiores com o **Toqan Router**. * Deployments on-premise são licenciados, e não medidos: os limites baseados no plano não se aplicam. Um limite único para todo o sistema pode ser aplicado com a variável de ambiente `ORQ_SYSTEM_RPM_LIMIT`. As rejeições por limite da plataforma retornam `429` com um header `Retry-After` e os headers `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`. ## Limites de orçamento Os [Budgets](/docs/pt-BR/ai-gateway/budgets.md) aplicam limites configurados a um destino nomeado. Um budget define um ou mais limites: **Cost** em USD, **Tokens** e **Requests per minute**. Consulte [Budgets](/docs/pt-BR/ai-gateway/budgets.md) para saber como configurá-los. O limite de solicitações por minuto sempre usa uma janela de 60 segundos que começa com a primeira solicitação, **independentemente do período de reinício**. Um budget mensal de `50 req/min` continua permitindo 50 solicitações em qualquer minuto, e o contador é reiniciado 60 segundos após a primeira solicitação da janela, e não no fim do mês. O período de reinício (Daily, Weekly, Monthly, Yearly, One-time) se aplica apenas aos limites de custo e de tokens. ### Limites em uma chave de API As chaves de API não têm campos de limite próprios. Defina limites de custo, tokens ou solicitações por minuto em uma chave criando um [Budget](/docs/pt-BR/ai-gateway/budgets.md) com escopo nessa **API Key**. A capacidade restante da chave fica visível na página de detalhes do budget, e a capacidade de custo e de tokens aparece nos headers de resposta `X-RateLimit-*-Cost` e `X-RateLimit-*-Tokens`. > [!NOTE] > > Os headers sem sufixo `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset` informam o rate limit da plataforma do plano em uma solicitação bem-sucedida, e não o limite de solicitações por minuto de um budget, porque o limitador da plataforma os grava por último. Os valores de solicitações por minuto de um budget aparecem nesses headers apenas em um `429` gerado por esse budget. Em vez disso, consulte o consumo de solicitações do budget na página de detalhes do budget. As chaves de API legadas, criadas antes do modelo unificado de chaves atual, não aceitam limites de custo, tokens ou taxa baseados em budgets. Crie uma chave de API atual e associe um [Budget](/docs/pt-BR/ai-gateway/budgets.md) a ela. ## Vários limites em uma solicitação Uma solicitação pode corresponder a vários budgets ao mesmo tempo: por exemplo, um budget com escopo no workspace e outro com escopo na chave de API que fez a chamada. Todos os budgets correspondentes são aplicados, e cada um acompanha o próprio uso. Prevalece o limite aplicável mais restritivo. Consulte [Níveis de budget e interação](/docs/pt-BR/ai-gateway/budgets.md#budget-levels-and-interaction) para conhecer as regras completas e exemplos práticos. ## Rate limits do provedor O provedor upstream aplica os próprios limites de taxa e de concorrência à conta por trás da integração do provedor. O gateway não coloca solicitações em fila: não há profundidade de fila, posição na fila nem timeout de fila para configurar. Quando o provedor retorna um erro de rate limit ou outro erro que permite nova tentativa: * O gateway mantém a solicitação aberta apenas durante o backoff da nova tentativa. Ele aguarda o intervalo `Retry-After` retornado pelo provedor e usa um backoff padrão quando esse intervalo não está presente. * Com uma [configuração de retry](/docs/pt-BR/ai-gateway/features/retries.md) na solicitação ou no agente, ele tenta novamente até a quantidade configurada dentro da mesma solicitação. * Com uma cadeia de fallback, uma série de tentativas esgotada passa para o próximo modelo. * Se todas as tentativas falharem, o erro do provedor é retornado ao chamador como resposta. ## A resposta 429 Quando qualquer limite é excedido, o gateway retorna `429 Too Many Requests` com um corpo de erro compatível com a OpenAI. As rejeições de budget incluem `scope_kind`, `scope_target_id` e `dimension`: ```json Budget rejection (requests per minute) theme={"theme":{"light":"github-light","dark":"github-dark"}} { "error": { "message": "Rate limit exceeded. Maximum requests allowed per minute.", "type": "rate_limit_error", "param": null, "code": "requests_per_minute_exceeded", "scope_kind": "workspace", "scope_target_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV", "dimension": "requests" } } ``` Os campos `code` e `dimension` identificam o limite excedido: | Código | Dimensão | Limite | | - | - | - | | `rate_limit_exceeded` | (ausente) | Rate limit da plataforma (plano de assinatura) | | `requests_per_minute_exceeded` | `requests` | Solicitações por minuto do budget | | `cost_budget_exceeded` | `cost` | Custo do budget | | `token_budget_exceeded` | `tokens` | Tokens do budget | `scope_kind` e `scope_target_id` identificam qual budget rejeitou a solicitação e estão presentes apenas em rejeições de budget. O texto de `message` varia conforme o tipo de limite; use o campo `code` para correspondência programática. ### Headers de rate limit Os headers de rate limit são emitidos por dimensão, e cada grupo de três só está presente quando a dimensão se aplica à solicitação. Portanto, uma resposta contém alguns desses headers, e não todos. Os headers aparecem tanto em solicitações bem-sucedidas (mostrando a capacidade restante) quanto em rejeições. | Header | Significado | Quando está presente | | - | - | - | | `X-RateLimit-Limit` | Solicitações por minuto permitidas pelo rate limit da plataforma do plano | Em todas as solicitações ao gateway | | `X-RateLimit-Remaining` | Solicitações restantes na janela atual | Em todas as solicitações ao gateway | | `X-RateLimit-Reset` | Segundos até a janela ser reiniciada (por exemplo, `42s`) | Em todas as solicitações ao gateway | | `X-RateLimit-Limit-Tokens` | Limite de tokens | Apenas quando um budget correspondente define um limite de tokens | | `X-RateLimit-Remaining-Tokens` | Tokens restantes no período atual | Apenas quando um budget correspondente define um limite de tokens | | `X-RateLimit-Reset-Tokens` | Segundos até o contador de tokens ser reiniciado (por exemplo, `42s`) | Apenas quando um budget correspondente define um limite de tokens | | `X-RateLimit-Limit-Cost` | Limite de custo em USD | Apenas quando um budget correspondente define um limite de custo | | `X-RateLimit-Remaining-Cost` | Custo restante no período atual (em USD) | Apenas quando um budget correspondente define um limite de custo | | `X-RateLimit-Reset-Cost` | Segundos até o contador de custo ser reiniciado (por exemplo, `42s`) | Apenas quando um budget correspondente define um limite de custo | | `Retry-After` | Segundos até o limite que causou a rejeição ser reiniciado, como um número inteiro simples (por exemplo, `42`). Os headers `X-RateLimit-Reset*` usam o formato `42s` | Apenas em rejeições | Dois casos removem headers que a tabela lista como sempre presentes. O trio sem sufixo `X-RateLimit-*` é omitido quando a solicitação não tem contexto de workspace e, em deployments on-premise, a menos que `ORQ_SYSTEM_RPM_LIMIT` esteja definido. `Retry-After` é omitido quando um budget que rejeitou a solicitação nunca é reiniciado por relógio, como um budget **One-time**. ### Retries e fallbacks `429` permite nova tentativa. O recurso de [Retries](/docs/pt-BR/ai-gateway/features/retries.md) do gateway tenta novamente em `429` por padrão, com backoff exponencial, e respeita o header `Retry-After`, e os [fallbacks](/docs/pt-BR/ai-gateway/features/retries.md#fallbacks) roteiam para um modelo de backup quando o principal atinge o rate limit. Os retries são executados dentro do gateway em uma única solicitação recebida (o limitador da plataforma conta as solicitações de entrada dos clientes, e não as chamadas upstream); portanto, não consomem cota adicional da plataforma nem do budget. ## Veja também > [card] [Budgets](/docs/pt-BR/ai-gateway/budgets.md) > > Crie budgets com limites de custo, tokens e solicitações por minuto e configure alertas. > [card] [Níveis de budget](/docs/pt-BR/ai-gateway/budgets.md#budget-levels-and-interaction) > > Como budgets em diferentes níveis interagem quando vários se aplicam à mesma solicitação. > [card] [Chaves de API](/docs/pt-BR/ai-gateway/configuration/api-keys.md) > > Crie e gerencie chaves de API do **AI Gateway** e associe um budget para limitar o uso. > [card] [Fallbacks e Retries](/docs/pt-BR/ai-gateway/features/retries.md) > > Tente novamente solicitações limitadas por taxa com backoff e roteie para modelos de fallback. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.