As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
Aplicação do limite de taxa
Este tópico descreve como o gateway avalia e impõe limites de taxa em tempo de execução, incluindo interação com outros recursos do gateway, formatos de resposta limitados e observabilidade.
Interação com regras de gateway
O gateway avalia os limites de taxa antes das regras do gateway. Se um limite de taxa limitar uma solicitação, a solicitação nunca alcançará o estágio de avaliação da regra.
Semântica de empilhamento
Quando vários limites de taxa se aplicam a uma solicitação, o gateway usa a lógica AND — todos os limites de taxa devem ser aprovados para que a solicitação continue. Se algum limite de taxa única negar a solicitação, o gateway a limitará.
Correspondência e especificidade de entradas
Quando um limite de taxa tem várias entradas, o gateway seleciona a entrada correspondente mais específica para os valores de dimensão resolvidos:
-
Uma correspondência de valor exata tem precedência sobre uma
*entrada. -
O
*valor significa “aplicar essa taxa a todos os valores dessa dimensão” — ele atua como uma entrada padrão. -
Para limites de taxa multidimensionais, o gateway usa um fallback final progressivo: ele primeiro tenta uma correspondência exata completa e depois substitui as dimensões finais por
*uma de cada vez até que uma correspondência seja encontrada.
O exemplo a seguir mostra como as entradas são comparadas para um limite de taxa com dimensionKeys: ["targetName", "toolName"] quando os valores resolvidos são["my-target", "readData"]:
| Dimensões de entrada | Fósforos? | Por que |
|---|---|---|
|
|
Sim (verificado primeiro) |
Correspondência exata em ambas as dimensões. Mais específico. |
|
|
Sim (marcado em segundo lugar) |
Correspondência exata na primeira dimensão, |
|
|
Sim (verificado pela última vez) |
Entrada padrão. Menos específico. |
A primeira entrada correspondente vence. Se nenhuma entrada corresponder (e nenhum * padrão existir), o limite de taxa será ignorado para essa solicitação.
Ordem de avaliação
O gateway avalia os limites de taxa na seguinte ordem:
-
O gateway avalia os limites de taxa com mais chaves de dimensão primeiro (limites mais específicos têm prioridade).
-
Dentro do mesmo número de dimensões, o gateway avalia primeiro os limites de taxa com taxas mais estreitas (mais baixas).
-
A avaliação causa curto-circuitos na primeira negação — o gateway não avalia os limites de taxa restantes.
Interação com limites gerenciados pelo serviço
O gateway impõe limites de taxa definidos pelo cliente e limites gerenciados pelo serviço. A taxa efetiva para qualquer solicitação é a mínima de ambas:
-
O gateway avalia primeiro os limites de taxa definidos pelo cliente.
-
Se a solicitação ultrapassar os limites do cliente, os limites gerenciados pelo serviço serão avaliados.
-
Uma negação de qualquer uma das fontes resulta em limitação.
Respostas limitadas
Quando uma solicitação é limitada, o gateway retorna uma resposta de erro específica do protocolo contendo o retryAfter valor no corpo da resposta.
Protocolo HTTP:
{ "error": "Rate limit exceeded", "success": false, "limitKey": "rl-abc123/targetName=my-target", "metric": "requests", "retryAfter": 1 }
Protocolo MCP (JSON-RPC):
{ "jsonrpc": "2.0", "id": "request-1", "error": { "code": -32003, "message": "Rate limit exceeded", "data": { "limitKey": "rl-abc123/targetName=my-target", "metric": "requests", "retryAfter": 1 } } }
OpenAI-compatible protocolo:
{ "error": { "message": "Rate limit exceeded", "type": "rate_limit_error", "code": "429", "limitKey": "rl-abc123/qualifiedModelId=anthropic.claude-3-sonnet", "metric": "tokens", "retryAfter": 60 } }
Anthropic-compatible protocolo:
{ "type": "error", "error": { "type": "rate_limit_error", "message": "Rate limit exceeded", "limitKey": "rl-abc123/qualifiedModelId=anthropic.claude-3-sonnet", "metric": "tokens", "retryAfter": 60 } }
O retryAfter campo indica quantos segundos o chamador deve esperar antes de tentar novamente. Use esse valor diretamente na sua lógica de repetição do lado do cliente.
Tempo de propagação
As alterações do limite de taxa (criar, atualizar, excluir) se propagam para o plano de dados em 30 segundos. Durante a propagação:
-
Os novos limites de taxa não são impostos até que a propagação seja concluída.
-
Os limites de taxa atualizados continuam aplicando a configuração anterior até que a atualização se propague.
-
Os limites de taxa excluídos continuam em vigor até que a exclusão se propague.
Precisão da aplicação e eventual consistência
A aplicação do limite de taxa é eventualmente consistente em vez de exata. A precisão da fiscalização é aproximada nos momentos após um limite começar a receber tráfego e melhora à medida que o tráfego continua. A precisão que você observa, portanto, depende do seu padrão de tráfego.
Os seguintes comportamentos são esperados:
-
Os limites de frio são exagerados no início. Um limite de frio é aquele que foi criado recentemente ou que não teve tráfego recente. Por um curto período inicial, o gateway pode admitir demais (permitir mais solicitações do que a taxa configurada) antes que a imposição converja. Quando um limite está sob tráfego contínuo, a precisão melhora e a taxa de aceleração observada se estabiliza perto da taxa configurada.
-
O tráfego sustentado é aplicado com precisão, mas rajadas curtas podem não ser aplicadas. Uma breve explosão contra um limite de frio pode passar sem ser estrangulada. A mesma taxa enviada como tráfego contínuo é aplicada, porque a precisão melhora à medida que o limite aumenta. Para observar ou demonstrar a fiscalização, envie o tráfego contínuo até o limite por vários minutos, em vez de uma única rajada curta. Por exemplo, para um limite de 4 solicitações por segundo, o gateway pode não limitar a 5ª solicitação no primeiro segundo. Se você enviar 5 solicitações por segundo continuamente, você sempre verá a solicitação extra ser limitada após o aquecimento do limite.
-
Taxas muito baixas são menos precisas. Taxas abaixo de aproximadamente 1 solicitação por segundo (por exemplo, um pequeno limite de solicitações por minuto) são mais difíceis de aplicar com precisão e mostrarão mais variabilidade. Prefira taxas mais altas quando a fiscalização precisa é importante e trate os limites muito baixos como aproximados.
-
Os limites dos tokens convergem mais lentamente. Token-per-minute os limites atualizam (reconciliam) o total de uso rastreado somente após a resposta do modelo. Uma solicitação que está em andamento por vários segundos ou minutos mantém apenas seu custo estimado no orçamento até ser concluída. Isso amplia a janela durante a qual o gateway pode admitir solicitações em excesso, em relação aos limites de solicitação. Consulte as perguntas frequentes sobre limite de taxa de token para obter detalhes.
Crie seus limites com base no uso justo e na proteção de back-end. Isso significa suavizar rajadas e proteger os alvos de vizinhos barulhentos em uma janela contínua, em vez de bloquear um número exato de solicitação no instante em que um limite é ultrapassado. Os limites de tarifa não são uma porta precisa e exata da solicitação. Os limites de taxa também não são um limite de segurança, conforme explicado na seção a seguir.
Fail-open comportamento
O gateway usa a semântica de abertura de falhas para avaliação do limite de taxa. A tabela a seguir descreve o comportamento quando o sistema de limite de taxa encontra erros:
| Cenário | Decisão | Lógica |
|---|---|---|
|
Limite de tarifa: tempo limite de serviço |
Permitir |
A disponibilidade tem precedência sobre a fiscalização. |
|
Chave de dimensão não resolvida a partir da solicitação |
Ignorar (permitir) |
O limite de taxa não se aplica a esse tipo de solicitação. |
|
Falha na atualização do cache do limite de taxa |
Tente novamente com dados obsoletos |
A última configuração conhecida é usada até que o cache seja recuperado. |
Importante
Devido ao comportamento de abertura de falhas, não confie apenas nos limites de taxa como limite de segurança. Use limites de taxa para gerenciamento de tráfego e qualidade de serviço e use regras de autenticação, autorização e WAF para impor a segurança.
Rastreamento com vãos OpenTelemetry
O gateway emite atributos de amplitude OpenTelemetry (OTEL) na extensão do servidor para cada solicitação em que os limites de taxa do cliente são avaliados. Use esses atributos para depuração e monitoramento.
| Atributo | Description | Exemplo |
|---|---|---|
|
|
A decisão de execução desta solicitação. |
|
|
|
O limite |
|
|
|
O tipo métrico que foi esgotado. Só está presente quando a decisão é tomada |
|
|
|
Comma-separated valores de dimensão resolvidos da entrada que acionou o acelerador. Só está presente quando a decisão é tomada |
|
|
|
Lista ordenada de todos os intervalos de limite de taxa verificados para esta solicitação. Cada entrada mostra o ID do limite de taxa, a métrica e os valores da dimensão resolvida. Presente para ambos |
|
O evaluated atributo é útil para entender quais limites de taxa se aplicam a uma solicitação, mesmo quando ela foi permitida. Cada entrada na lista segue o formato{rateLimitId}:{metric}:{resolvedDimVal1,dimVal2,…}.
