Limite de taxa da API de agentes de IA: novas tentativas seguras

Um agente que atinge uma cota deve diminuir o ritmo, contabilizar cada tentativa extra e parar antes que uma recusa temporária se transforme em um problema operacional maior. «Tentar novamente em caso de falha» é um conselho adequado para uma pessoa clicando em um botão. É perigoso para um processo capaz de emitir solicitações mais rápido do que qualquer pessoa consegue acompanhar.

A parte difícil não é esperar alguns segundos. O difícil é preservar o significado da tarefa original quando a primeira solicitação pode ter falhado antes de chegar ao provedor, depois de o provedor concluí-la ou porque várias execuções de agentes esgotaram uma mesma cota compartilhada. Um projeto seguro separa esses casos e transforma a intervenção humana em um resultado previsto, não em uma exceção constrangedora.

Um 429 é uma instrução de agendamento, não um erro para bombardear

HTTP 429 significa que o servidor está recusando a solicitação porque o cliente enviou solicitações demais em um período controlado pelo servidor. A RFC 6585 define o código de status e diz que a representação da resposta deve explicar a condição e pode incluir um cabeçalho Retry-After. Essa formulação é importante: um 429 não informa ao agente que repetir imediatamente a mesma solicitação tem alguma chance de funcionar.

Primeiro, o agente deve registrar o provedor, o endpoint, a identidade da credencial ou da conta, a classe da solicitação, o status da resposta e todos os cabeçalhos de limite de taxa. Em seguida, deve colocar o trabalho em estado adiado. Não deixe o modelo de linguagem decidir isso em prosa depois de cada falha. A camada de transporte precisa de um comportamento determinístico, porque um modelo pressionado pela tarefa frequentemente tentará um endpoint parecido, mudará um filtro ou criará um segundo caminho de solicitação. Essas improvisações podem multiplicar as chamadas e produzir a mesma recusa.

Uma recusa muitas vezes se aplica a um bucket mais amplo que a solicitação atual. Os provedores costumam definir limites por conta, projeto, token, endereço IP, família de endpoints ou uma combinação desses elementos. Um agente pode receber 429 enquanto outro agente que usa a mesma credencial continua funcionando por algum tempo. Isso não prova que o primeiro possa tentar novamente com segurança. Pode significar que o provedor tem vários buckets ou que o segundo processo está consumindo a capacidade restante.

Mantenha um registro local para cada escopo conhecido. Se o serviço documentar um limite por token, agrupe as solicitações por token. Se fornecer apenas orientações no nível da conta, presuma que todos os workers dessa conta compartilham o bucket até que haja evidências em contrário. Um registro local não reproduzirá perfeitamente o contador interno do provedor, mas impede que seus próprios workers disputem recursos às cegas.

A especificação IETF RateLimit Fields, RFC 9333, define RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Esses campos descrevem o estado da cota, mas não anulam um 429 já recebido. Use-os para controlar o ritmo das próximas solicitações e evitar encher a fila mais rápido do que o provedor consegue aceitar. Considere o escopo conforme a documentação do provedor, porque um cabeçalho sozinho pode não revelar se se aplica a um endpoint ou a uma conta inteira.

Um registro de estado útil se parece com isto:

{
  "provider": "billing-api",
  "scope": "account:ops-team",
  "request_class": "write:invoice",
  "next_allowed_at": "2025-04-08T14:12:31Z",
  "remaining": 0,
  "reset_after_seconds": 60,
  "source": "HTTP 429 Retry-After"
}

O executor do agente deve ler esse registro antes de despachar outra chamada. Dormir dentro de um único handler de solicitação é aceitável em uma execução pequena pela linha de comando. Uma fila com um next_allowed_at visível é melhor quando existem vários workers, ferramentas ou tarefas retomadas. Ela permite que o agendador escolha outro trabalho em vez de manter um processo ocupado e oferece ao operador uma explicação clara para o atraso.

Orçamentos de novas tentativas impedem que uma pequena falha vire uma enxurrada

Um orçamento de novas tentativas estabelece um teto rígido para o trabalho extra que uma tarefa pode criar depois de uma chamada com falha. Conte tanto as tentativas quanto o tempo de espera transcorrido. Apenas uma quantidade fixa falha quando o serviço pede que os clientes esperem minutos; apenas um limite de tempo falha quando um loop rápido de novas tentativas consome a cota da conta em segundos.

Use orçamentos separados para cada tarefa e para cada escopo compartilhado do provedor. O orçamento da tarefa responde: «Quanto de incerteza este objetivo pode tolerar?». O orçamento do escopo responde: «Quanta perturbação todo o trabalho atual pode impor a este provedor?». Se dez tarefas receberem três novas tentativas cada, a conta ainda poderá receber trinta solicitações extras. É assim que uma política aparentemente conservadora vira uma rajada.

Para solicitações de leitura comuns, uso um orçamento pequeno e um prazo menor que o valor comercial da resposta. Para gravações, gasto muito menos orçamento em novas tentativas sem confirmação. O custo de esperar por uma pessoa pode ser menor que o custo de duplicar um pagamento, enviar avisos duplicados ou aplicar uma implantação duas vezes.

Represente a regra como dados que o agente não possa substituir casualmente:

request_classes:
  read:
    max_attempts: 4
    max_wait_seconds: 90
    retry_statuses: [408, 429, 500, 502, 503, 504]
  idempotent_write:
    max_attempts: 3
    max_wait_seconds: 120
    retry_statuses: [408, 429, 502, 503, 504]
  uncertain_write:
    max_attempts: 1
    max_wait_seconds: 0
    retry_statuses: []
shared_scope:
  max_delayed_requests: 25
  max_concurrent_requests: 2

Esse trecho impede uma falha conhecida: o agente recebe um timeout depois de enviar uma gravação, presume que nada aconteceu e tenta novamente contra um provedor já sob pressão. A classe uncertain_write força uma verificação de status ou uma escalação. Ela não recompensa o agente por insistir quando a insistência pode mudar o resultado.

O orçamento deve contabilizar todas as tentativas reais, inclusive as iniciadas por bibliotecas. Já vi controles de novas tentativas declarados na aplicação enquanto um cliente HTTP, um executor de workflows e um proxy repetiam as chamadas por baixo dela. A quantidade resultante de solicitações parecia misteriosa até que alguém examinou os três padrões. Escolha uma camada para controlar as novas tentativas. Configure todas as outras para reportar erros sem repetir a chamada ou torne seu comportamento explícito e inclua-o no orçamento total.

O esgotamento do orçamento deve produzir um resultado terminal com contexto, não uma falha genérica. O resultado deve dizer se a solicitação original foi enviada, se chegou uma resposta, quantas tentativas ocorreram, quanto tempo a tarefa esperou e qual é a próxima ação segura. Assim, o agente pode continuar com trabalho não relacionado ou apresentar uma escalação precisa, em vez de pedir repetidamente a si mesmo para «tentar novamente».

O backoff precisa de jitter e de um limite máximo

O backoff exponencial reduz a pressão depois de recusas repetidas ao aumentar o intervalo entre as tentativas. O jitter impede que muitos workers que falharam ao mesmo tempo retornem em uma onda sincronizada. Ambos pertencem ao cliente, mesmo quando o provedor publica um horário de redefinição, porque a simultaneidade interna pode criar sua própria avalanche de solicitações.

Para o número da tentativa n, em que a primeira nova tentativa é n = 1, calcule um teto e escolha um atraso aleatório dentro dele:

import random

BASE_SECONDS = 1.0
MAX_SECONDS = 60.0

def retry_delay(attempt_number: int) -> float:
    cap = min(MAX_SECONDS, BASE_SECONDS * (2 ** attempt_number))
    return random.uniform(0, cap)

Esse é o jitter completo. Ele evita a armadilha de fazer todos os workers dormirem exatamente 2, 4, 8 e 16 segundos. Atrasos fixos iguais são populares porque facilitam a leitura dos logs. Também tornam as novas tentativas coordenadas fáceis de prever, o oposto do que um serviço ocupado precisa.

Quando uma resposta fornece Retry-After, esse valor prevalece sobre um atraso local calculado que seja menor. A RFC 9110 permite que Retry-After seja um atraso em segundos ou uma data HTTP. Analise os dois formatos. Se a data já tiver passado porque o relógio da máquina difere do relógio do provedor, aplique um atraso mínimo moderado em vez de repetir em um loop acelerado.

Não use backoff como substituto para controlar o ritmo. O backoff começa depois de uma falha. Um token bucket, leaky bucket ou limite simples no agendador controla a taxa antes da falha. Se um provedor permitir uma quantidade conhecida de solicitações em um intervalo conhecido, mantenha o ritmo abaixo da cota publicada e reserve espaço para o trabalho interativo. O agendador também deve limitar a simultaneidade. Vinte solicitações simultâneas podem consumir a capacidade de um intervalo curto antes que qualquer worker leia uma resposta RateLimit-Remaining.

Uma regra prática de despacho é simples: antes de enviar uma chamada, verifique o próximo horário permitido do escopo compartilhado e se há uma vaga de simultaneidade. Depois de um 429, atualize o registro do escopo antes de agendar qualquer nova tentativa. A ordem importa. Se os workers agendarem novas tentativas antes de publicar a recusa, cada um poderá concluir que é dono da próxima vaga.

Limite o atraso e o tempo total de espera. Uma curva exponencial sem teto pode adiar uma tarefa por horas e manter uma execução obsoleta ativa muito depois de suas premissas terem expirado. O agente deve encerrar a tarefa ou entregá-la a um agendador depois do prazo, preservando a entrada original para análise posterior.

A idempotência decide se uma nova tentativa é segura

Uma solicitação idempotente produz o mesmo efeito pretendido quando repetida. Isso não significa que toda solicitação que usa HTTP PUT seja inofensiva em qualquer aplicação, nem que todo POST seja perigoso. A RFC 9110 descreve métodos como PUT e DELETE como idempotentes em sua intenção, enquanto POST geralmente não é idempotente. O contrato real da API do provedor determina o risco operacional.

Solicitações de leitura normalmente toleram novas tentativas, desde que o agente aceite que os dados retornados podem ter mudado. Uma solicitação de exclusão também pode tolerar uma repetição se excluir um recurso já ausente produzir um resultado conhecido e aceitável. Criar um pagamento, convite, chamado de suporte, pedido de compra ou implantação geralmente não tolera repetição sem confirmação. Essas são as chamadas que exigem mais cautela depois de um timeout ou reset de conexão.

O setor costuma misturar dois estados diferentes:

• Uma solicitação que certamente não chegou ao provedor pode ser enviada novamente se a própria operação permitir isso.
• Uma solicitação cujo resultado é desconhecido precisa de reconciliação antes que o agente envie outro efeito colateral.

Uma falha de conexão depois que o cliente escreve os bytes não prova que o provedor deixou de agir. O servidor pode ter concluído a operação e perdido a conexão da resposta. O agente não pode inferir o resultado a partir da ausência de resposta.

Quando um provedor oferece uma chave de idempotência, gere um token estável por ação lógica e reutilize-o em todas as tentativas dessa ação. Não gere um token novo a cada tentativa. Um token novo informa ao provedor que cada nova tentativa é uma operação separada, anulando a proteção.

POST /v1/transfers HTTP/1.1
Idempotency-Key: transfer-7c41b5b9-7f5b-4f51
Content-Type: application/json

{"source":"acct_17","destination":"acct_42","amount":12500,"currency":"USD"}

Armazene o token junto da tarefa e do payload da solicitação antes de enviar a primeira chamada. Se o executor for reiniciado, ele deverá recuperar o mesmo token. Armazene também o identificador da operação retornado pelo provedor. Esse identificador permite que uma chamada posterior de reconciliação consulte a ação original sem recriá-la.

Se a API não oferecer idempotência, procure um padrão de criação seguido de consulta. O agente pode anexar ao payload uma referência externa gerada pelo cliente e depois pesquisar por essa referência após uma falha incerta. Se a API não oferecer nem idempotência nem uma consulta confiável, não automatize gravações repetidas. Peça a uma pessoa que examine os registros do provedor. Isso parece mais lento até que o primeiro efeito colateral duplicado chegue a um sistema que não consegue desfazê-lo corretamente.

Separe limites de taxa, indisponibilidade e solicitações inválidas

Uma política de novas tentativas que trate todo status diferente de sucesso da mesma forma ocultará defeitos e desperdiçará a cota. Classifique a resposta antes de escolher um atraso. O código de status, o corpo da resposta, o código de erro do provedor e o método da solicitação são relevantes.

Use esta divisão prática:

• 429 significa reduzir o ritmo, respeitar as orientações do provedor e debitar o orçamento compartilhado de limite de taxa.
• 408, resets de conexão e algumas respostas 5xx podem justificar uma nova tentativa limitada, mas as operações de gravação ainda precisam de um caminho de idempotência ou reconciliação.
• 400, 401, 403, 404 e 422 geralmente exigem uma solicitação corrigida, uma autorização diferente ou uma decisão humana. Repeti-las é desperdício.
• 409 exige tratamento específico do recurso. Pode significar uma duplicata, um conflito de versão ou um bloqueio mantido por outro workflow.
• Um erro específico do provedor indicando esgotamento da cota pode exigir espera até uma redefinição de faturamento ou diária, algo diferente de um limite de rajada curta.

Não trate 503 Service Unavailable como uma forma equivalente de 429. Um 503 informa que o serviço não consegue atender à solicitação naquele momento; um 429 informa que o cliente excedeu um limite. Ambos podem trazer Retry-After, mas um 429 deve fazer o agendador reduzir a vazão local do escopo afetado. Um 503 pode ser regional, específico de um endpoint ou abranger todo o provedor. Preserve essa distinção nas métricas e nas mensagens aos operadores.

O comportamento do agente também pode causar tempestades de solicitações inválidas. Um modelo pode chamar repetidamente um endpoint com um filtro não compatível depois de receber 422, ou repetir 401 depois que a credencial foi revogada. Coloque um disjuntor em torno de falhas idênticas repetidas. Por exemplo, se o mesmo endpoint, método e código de erro normalizado falharem várias vezes em uma execução, interrompa esse caminho e devolva os detalhes do erro ao agente como uma restrição. Não permita que ele altere espaços em branco, reordene campos JSON e finja estar explorando novas opções.

Uma impressão digital normalizada da solicitação deve excluir segredos e cabeçalhos voláteis. Inclua o método, o modelo do endpoint, os campos estáveis do payload e o código de erro da API. Isso permite que o executor identifique um loop sem registrar credenciais ou corpos sensíveis completos.

Credenciais compartilhadas precisam de uma fila, não de agentes bem-intencionados

Uma credencial de API compartilhada cria um problema de coordenação que agentes individuais não conseguem resolver com boas intenções. Cada processo vê apenas suas próprias solicitações, a menos que um agendador forneça um orçamento comum. O backoff por agente reduz a chance de uma rajada, mas não distribui de forma justa uma cota escassa para toda a conta.

Coloque uma fila de saída diante do escopo da credencial compartilhada. Defina a prioridade de forma deliberada. Uma alteração de produção aprovada por uma pessoa pode ter precedência sobre o trabalho de inventário em segundo plano. Um agente de longa duração que descubra dez mil registros deve percorrê-los na velocidade permitida pelo provedor, em vez de encher a fila com todas as solicitações de páginas de uma só vez.

A fila precisa de cancelamento. Se a tarefa principal de um agente terminar, descarte suas solicitações adiadas antes que sejam ativadas. Caso contrário, uma tarefa interrompida poderá continuar consumindo cota mais tarde e tornar o registro de auditoria confuso. O cancelamento também deve liberar qualquer vaga de simultaneidade reservada.

Use uma regra de agrupamento de solicitações para leituras seguras. Se cinco execuções de agentes pedirem o mesmo registro imutável em um intervalo curto, faça uma solicitação e distribua o resultado a todas as tarefas em espera. Não agrupe leituras em que a atualização mude o significado, como saldo ou status de aprovação. O objetivo é remover duplicatas acidentais, não criar um cache que devolva fatos desatualizados a um agente que está tomando decisões.

Os limites de taxa muitas vezes revelam um problema de planejamento mais profundo. Um agente que chama um endpoint de detalhes uma vez por item pode estar seguindo exatamente suas instruções e, ainda assim, usando o padrão de acesso errado. Antes de adicionar novas tentativas, procure endpoints em lote, controles de paginação, solicitações condicionais, webhooks, jobs de exportação ou um endpoint de pesquisa no servidor. Essas mudanças reduzem as chamadas antes que o provedor precise recusá-las.

O Sallyport pode manter as credenciais de API fora do processo do agente e registrar as chamadas individuais de saída, mas o chamador ainda precisa de controles de fila e de novas tentativas. Separar as credenciais reduz a exposição de segredos; não altera a cota do provedor.

A escalação humana deve preservar a incerteza

Uma pessoa deve assumir quando o sistema não conseguir estabelecer se um efeito colateral ocorreu, quando o tempo restante de espera exceder o prazo da tarefa, quando a cota compartilhada estiver esgotada ou quando limites repetidos apontarem para um problema de configuração da conta. Escalação não é uma notificação genérica de «falha da API». É um pequeno dossiê que permite uma decisão sem reconstruir a execução a partir de logs espalhados.

Envie ao operador estes fatos:

• o resultado solicitado pela tarefa e a ação lógica exata que foi interrompida;
• o provedor, endpoint, método, escopo da conta e impressão digital sanitizada da solicitação;
• horários das tentativas, status, cabeçalhos Retry-After ou de limite de taxa e orçamento consumido;
• se a operação tem um token de idempotência, um ID de operação do provedor ou uma consulta de reconciliação;
• as próximas opções seguras, como esperar, consultar o status, aumentar a cota, alterar o plano ou cancelar.

Não coloque um corpo bruto de solicitação em um cartão de aprovação por padrão. Ele pode conter dados pessoais, conteúdo de documentos internos ou um valor que parece inofensivo até chegar à pessoa errada. Mostre um resumo conciso e torne o acesso detalhado uma ação de auditoria intencional.

A aprovação deve solicitar uma decisão, não apenas consentimento para «continuar». Para uma gravação incerta, ofereça «consultar a operação existente», «tentar novamente com o mesmo token de idempotência», «cancelar» e, quando justificado, «enviar uma nova operação». A última opção deve declarar claramente que pode criar um segundo efeito colateral. As pessoas tomam decisões melhores quando as opções descrevem o risco real.

Uma aprovação para acesso contínuo e uma aprovação para uma ação externa específica são controles diferentes. Uma sessão pode continuar autorizada enquanto o agente ainda precisa de revisão por chamada para um pagamento, uma gravação em produção ou uma nova tentativa depois de um evento de limite. Mantenha essas decisões separadas tanto na interface quanto no log.

Ao revisar uma escalação, comece pela reconciliação. Consulte o provedor pela chave de idempotência, pela referência externa ou pelo identificador da operação. Só tente novamente depois que a consulta mostrar que nenhuma ação foi concluída ou depois que o provedor garantir a supressão de duplicatas. Essa ordem é mais lenta que um reenvio cego por uma viagem de rede. Ainda assim, é mais rápida que reparar uma duplicata que entrou em um livro contábil downstream.

Os registros de auditoria devem explicar a ação tentada e a espera

Um bom registro de auditoria responde a mais do que «a solicitação retornou 200?». Ele deve mostrar o que o agente tentou fazer, qual autorização permitiu a ação, o que o serviço remoto retornou e como o controlador de novas tentativas reagiu. Sem o registro da decisão, uma sequência de chamadas pode parecer repetição descuidada, mesmo quando o agendador obedeceu a um valor documentado de Retry-After.

Registre um evento antes do despacho e depois acrescente os eventos de resultado e agendamento. Mantenha os metadados da solicitação livres de credenciais em texto simples. Uma sequência compacta poderia ser:

14:11:02 action_requested  task=sync-482 method=POST route=/records
14:11:02 action_sent       attempt=1 idempotency=rec-91f2
14:11:03 action_result     status=429 retry_after=30 scope=account:ops
14:11:03 retry_scheduled   attempt=2 due=14:11:33 budget_wait=30
14:11:33 action_sent       attempt=2 idempotency=rec-91f2
14:11:34 action_result     status=201 provider_id=r_893

Essa sequência separa uma ação lógica das tentativas de transporte. Se alguém perguntar por que ocorreram duas chamadas POST, o registro mostra que elas compartilharam um token de idempotência e respeitaram um atraso indicado pelo provedor. Se a segunda resposta tivesse sofrido timeout, o próximo evento deveria ser reconciliation_required, e não outro action_sent automático.

O registro à prova de adulteração traz um benefício prático durante a análise de incidentes: permite que a equipe verifique se uma execução não apagou tentativas inconvenientes depois do fato. O Sallyport projeta seu diário de sessões e chamadas a partir de um log de auditoria criptografado e encadeado por hash, e sp audit verify verifica a cadeia offline sem precisar de uma chave do cofre. Isso é útil quando um operador precisa distinguir uma limitação do provedor de um loop do agente ou de uma nova tentativa manual tardia.

Os logs também precisam de limites de retenção e acesso. Um caminho de solicitação, o identificador da conta do provedor e um padrão de horários podem revelar atividade operacional sensível mesmo quando o token nunca aparece. Capture o suficiente para reconstruir a decisão e limite quem pode pesquisar e exportar o registro.

Teste os caminhos de falha antes que um agente os encontre em produção

Um projeto de limite de taxa só está completo quando um teste prova que ele interrompe chamadas, preserva a idempotência e escala a incerteza. Simular um único 429 não basta. Você precisa de workers simultâneos e de falhas que ocorram depois que o serviço remoto pode ter agido.

Execute esta sequência em um ambiente de teste ou contra uma API falsa controlável:

1. Inicie três tarefas de agentes que usem um único escopo de conta simulado e emitam a mesma solicitação de leitura segura.
2. Retorne 429 com Retry-After: 10 para a primeira solicitação e verifique se o agendador atrasa todo o trabalho desse escopo, em vez de permitir que os outros dois continuem em velocidade máxima.
3. Retorne sucesso depois do atraso e confirme que os horários das novas tentativas variam um pouco, em vez de chegarem como uma única rajada.
4. Envie uma gravação com um token de idempotência estável, simule uma queda de conexão depois que a API falsa armazenar o registro e verifique se o executor consulta o status em vez de emitir uma nova criação.
5. Esgote o orçamento de tempo configurado e verifique se o operador recebe o registro de escalação sanitizado e se o trabalho cancelado nunca é reativado mais tarde.

Meça as tentativas de saída na API falsa, não apenas as chamadas de funções dentro do agente. Contadores internos não detectam novas tentativas adicionadas por bibliotecas HTTP ou wrappers. Teste também uma reinicialização: pare o executor depois da primeira gravação incerta, restaure seu estado persistido e confirme que ele retoma a reconciliação com o token de idempotência original.

Não recompense o ambiente de testes do agente por obter uma resposta de sucesso no fim. Recompense-o por fazer a quantidade correta de chamadas, esperar quando receber essa instrução e deixar uma gravação ambígua sem resolução até ter evidências. Um agente que «conclui o trabalho» duplicando ações externas não passou no teste.

O primeiro controle a implementar é um orçamento compartilhado de novas tentativas com resultados terminais explícitos. Ele transforma a limitação de taxa de um convite para continuar tentando em uma decisão operacional com registro, prazo e uma pessoa que pode intervir quando o estado remoto for incerto.