Tentativas, limites e duplicados em APIs de IA: como evitar que uma falha execute uma ação duas vezes

O problema: uma resposta perdida não equivale a uma operação com falha

Em uma integração com uma API de IA, um timeout normalmente descreve um fato limitado: o cliente não recebeu uma resposta dentro do prazo configurado. Por si só, ele não permite concluir que o provedor não recebeu a solicitação, não a processou ou não iniciou uma ação posterior. A conexão pode ser interrompida depois que o servidor aceita a solicitação; a resposta pode se perder depois que a operação é concluída; e um processo local pode reiniciar quando o resultado já existe fora dele.

Essa distinção importa ainda mais quando uma saída do modelo aciona efeitos operacionais. Repetir uma geração de texto pode produzir uma resposta diferente e consumir recursos, mas, em geral, não altera um sistema de negócio. Repetir uma instrução que envia um e-mail, cria uma reserva, registra um pagamento, modifica um processo ou invoca uma ferramenta pode, sim, produzir um efeito duplicado. A segurança do fluxo não deve depender de o modelo devolver o mesmo texto nem de uma única chamada de rede sempre chegar ao fim.

A semântica de HTTP ajuda a estabelecer o limite do problema: uma solicitação idempotente é aquela cujo efeito pretendido no servidor permanece equivalente mesmo que seja executada mais de uma vez. Isso não significa que toda repetição seja gratuita, que a resposta seja idêntica ou que não haja registros adicionais. Significa que o efeito relevante deve poder ser aplicado repetidamente sem alterar o resultado final esperado. Em fluxos de IA, essa propriedade deve ser verificada tanto na chamada ao provedor quanto, de forma independente, em cada sistema externo que receba uma ação.

Um modelo mental: solicitação, operação lógica, tentativa, efeito e confirmação

É útil separar cinco conceitos que costumam ser confundidos. A operação lógica é a intenção de negócio: por exemplo, «emitir uma resposta estruturada para o processo X» ou «enviar uma única notificação de aprovação». A solicitação é uma mensagem concreta enviada a uma API. Uma tentativa é cada envio dessa solicitação, incluindo o primeiro e suas repetições. O efeito externo é a alteração observável em um destino: uma mensagem enviada, uma linha criada ou uma compra confirmada. A confirmação é a evidência que permite marcar a operação lógica como concluída, rejeitada ou pendente de revisão.

Um mesmo identificador de operação deve vincular todas as tentativas que perseguem uma única intenção. Ele deve ser criado antes da primeira chamada e persistido fora da memória do processo, para sobreviver a falhas, implantações e trabalhos em segundo plano. Não use como identidade apenas um identificador de solicitação devolvido por um provedor: ele pode não existir se houve uma falha antecipada e, mesmo quando existe, normalmente identifica uma tentativa, e não toda a intenção de negócio.

Além do identificador de operação, mantenha uma chave de idempotência estável para o destinatário que a aceite. A chave deve ser mantida ao repetir a mesma operação lógica e alterada quando a intenção mudar. Gerar uma nova chave a cada tentativa anula a deduplicação. Reutilizar uma chave para duas operações diferentes pode fazer uma ação legítima ser confundida com uma repetição. O registro deve guardar a relação entre operação, tentativa, destino, chave usada e resultado observado.

Classifique o risco antes de automatizar uma nova tentativa

Não existe uma política única adequada para todas as chamadas. Classificar a operação pelo risco de repetição obriga a decidir o que precisa ser protegido. Leituras ou consultas sem efeitos costumam admitir novas tentativas quando o custo e a carga estão sob controle. A geração de texto sem efeitos externos pode ser repetida, mas o resultado pode variar; portanto, a aplicação deve decidir se aceita uma nova saída, preserva uma parcial ou apresenta o caso como pendente.

Uma escrita idempotente pode ser repetível se o destino garantir que a mesma chave representa a mesma operação. Uma escrita compensável pode exigir uma reversão posterior, mas a compensação não torna automaticamente segura uma nova tentativa: ela também pode falhar, chegar tarde ou ter efeitos próprios. Ações irreversíveis ou difíceis de verificar exigem uma barreira maior, como confirmação humana, uma reserva prévia ou uma consulta confiável ao sistema de destino antes de agir.

Essa classificação deve ser aplicada ao fluxo completo, e não apenas à chamada ao modelo. Um modelo pode gerar corretamente uma chamada de ferramenta e, ainda assim, a ferramenta pode ter sido executada antes que a resposta se perdesse. A saída textual posterior não é evidência suficiente de que o efeito ocorreu exatamente uma vez. A camada que executa ferramentas deve registrar e deduplicar a ação com seus próprios controles.

Projete a idempotência em duas fronteiras

Deduplicar uma chamada ao provedor e deduplicar um efeito de negócio são problemas relacionados, mas não equivalentes. Mesmo que uma API de modelo aceite uma chave de idempotência, essa proteção não prova que uma ferramenta downstream, um provedor de e-mail ou um sistema de pagamentos aplicou seu efeito uma única vez. Da mesma forma, uma ferramenta idempotente não elimina o custo nem a saturação de repetir desnecessariamente uma solicitação de inferência.

A prática mais robusta é estabelecer duas fronteiras. Na primeira, o wrapper da API registra a operação e associa as tentativas a uma chave estável quando o contrato do provedor oferecer suporte a isso. Na segunda, o executor de ações externas usa um identificador de efeito próprio e um armazenamento durável de deduplicação. Antes de executar, ele verifica se já existe uma ação concluída para aquela operação; se existir, devolve o resultado já existente. Se não existir, registra o início de modo que uma reinicialização posterior permita continuar a investigação.

Não invente capacidades de reconciliação que o contrato real não oferece. As fontes disponíveis descrevem práticas gerais de tentativas e semântica HTTP, mas não documentam, para cada API de IA, uma consulta universal de status de operação nem uma chave de idempotência aplicável a todos os endpoints. Revise a documentação contratual do endpoint específico antes de depender de qualquer uma dessas funções.

Política de tentativas: orçamento, backoff e jitter

Uma política segura expressa limites antes de o erro ocorrer. Ela deve definir quais famílias de falhas são candidatas a uma nova tentativa, o máximo de tentativas, um deadline global da operação, uma espera máxima aceitável e o custo máximo tolerado. O número de tentativas, isoladamente, não basta: cinco novas tentativas podem ultrapassar o prazo do usuário, esgotar uma cota ou manter trabalhadores ocupados que deveriam liberar capacidade.

Respostas de limitação de taxa e erros transitórios do servidor podem justificar uma espera e uma nova tentativa, desde que a operação seja repetível e ainda haja orçamento. A documentação do OpenClaw indica que determinados SDKs baseados em Stainless podem tratar como repetíveis respostas 408, 409, 429 e da família 5xx. Isso descreve uma política de SDK nesse contexto, não uma regra universal para qualquer endpoint ou efeito externo. Erros que indicam uma solicitação inválida, uma autorização ausente ou uma condição de negócio não são corrigidos repetindo dados idênticos; exigem corrigir a causa ou interromper o fluxo.

Use backoff exponencial para ampliar progressivamente o intervalo e jitter para evitar que muitos clientes tentem de novo ao mesmo tempo. A AWS recomenda tanto o backoff exponencial quanto a variação aleatória, além de limitar as tentativas e verificar a idempotência antes de repetir. Se uma resposta indicar quanto esperar por meio de um sinal de nova tentativa, respeite-o quando for válido e compatível com o deadline da operação. Se a espera ultrapassar o orçamento, registre o motivo do adiamento ou da falha, em vez de continuar esperando sem limite.

Limites de taxa e saturação: a nova tentativa também é carga

Um erro 429 indica que a capacidade disponível ou o limite aplicável não permite continuar naquele momento; ele não demonstra que aumentar a pressão resolverá o problema. Tentar novamente imediatamente pode transformar um incidente limitado em uma tempestade de tráfego. Além disso, tentativas com falha podem ser contabilizadas nos limites de taxa, de modo que uma estratégia agressiva pode atrasar ainda mais as operações válidas.

Controle a concorrência na fila de trabalho, e não apenas dentro de cada cliente. Estabeleça limites por provedor, modelo, credencial e tipo de operação quando isso for pertinente. Reserve capacidade para reconciliar estados ambíguos e para operações prioritárias; caso contrário, uma onda de novas tentativas pode impedir que o sistema determine o que aconteceu. O orçamento deve incluir tempo de fila, tempo de conexão, tempo de processamento e esperas entre tentativas.

O guia da OpenAI sobre erros 429 recomenda backoff exponencial com variação aleatória quando não há uma indicação de espera utilizável, e aconselha limitar tanto o número de tentativas quanto o tempo total dedicado a elas. É importante diferenciar uma limitação transitória de outros problemas de conta ou cota que não são resolvidos esperando. A decisão deve se basear nas informações do erro e no contrato da integração, e não somente no código de status.

Estados ambíguos: reconcilie antes de repetir

O estado ambíguo aparece quando não há confirmação suficiente para decidir se o efeito ocorreu. Ele deve ser um estado explícito e persistente, não uma exceção apagada quando um processo reinicia. Registre, no mínimo, o identificador de operação, os dados ou um resumo seguro da intenção, os identificadores de tentativa, as marcas temporais, a chave de idempotência, o destino, a categoria do erro e qualquer identificador devolvido antes da interrupção.

A reconciliação segue uma hierarquia. Primeiro, use uma consulta de status ou um identificador de recurso se o contrato do destinatário o fornecer. Depois, procure o efeito no sistema de destino com um critério estável, como o identificador de operação incluído nos metadados. Se a evidência confirmar o efeito, encerre a operação sem repetir. Se ela provar que o efeito não foi aplicado, será possível abrir uma nova tentativa de acordo com a política. Se não permitir distinguir os dois casos, não presuma ausência: mantenha o caso pendente e escale-o quando o risco justificar.

A revisão humana não é uma falha de desenho; ela é um controle de segurança para operações cujo custo de duplicação supera o custo da demora. As condições de escalonamento devem ser concretas: cobranças financeiras, comunicações irreversíveis, alteração de registros regulados, inconsistência entre fontes, vencimento do deadline ou ausência de uma prova confiável de deduplicação.

Padrões para saídas estruturadas, ferramentas e agentes

Para saídas estruturadas, separe a validação da execução. Uma resposta que não cumpre o esquema não deve alimentar diretamente uma ferramenta. Armazene a saída recebida, valide tipos, campos obrigatórios, faixa de valores e autorização da ação proposta. Se decidir pedir uma nova geração, trate-a como uma nova tentativa de produzir um plano, e não como prova de que nenhuma ferramenta foi executada antes.

Em tool calling, o controlador deve ser a autoridade sobre a execução. O modelo pode propor uma chamada, mas o controlador deve atribuir o identificador de operação, verificar permissões, deduplicar argumentos semanticamente equivalentes quando for apropriado e registrar o resultado. Se o agente for retomado após uma falha, ele deve recuperar o registro das ferramentas já executadas; não deve inferir o histórico a partir do texto de uma conversa.

Para agentes com múltiplas etapas, evite repetir todo o fluxo composto como uma unidade opaca. Tente novamente etapas individuais apenas quando seus limites e garantias forem conhecidos. Um planejamento pode ser gerado de novo; uma leitura pode ser repetida com aviso sobre dados variáveis; uma escrita deve ser reconciliada; e uma ação irreversível exige uma barreira explícita. Esse desenho reduz duplicados e também melhora a auditabilidade quando o sistema recebe resultados parciais.

Checklist de produção e limites deste guia

Antes de ativar novas tentativas automáticas, documente para cada operação seu responsável, destino, efeitos, custo de duplicação, chave de idempotência, evidência de confirmação, deadline, número máximo de tentativas e condição de escalonamento. Teste falhas em cada fronteira: antes de enviar, durante a transmissão, depois que o destino aceita a solicitação e antes de persistir a resposta local. Um teste útil verifica que uma reinicialização do processo não cria um segundo efeito.

Revise também a arquitetura no contexto do centro de aprendizagem, da documentação de segurança, dos critérios de preços e do glossário do seu produto. O limite de tentativas afeta o custo e a latência; a retenção de registros afeta a privacidade; e as credenciais usadas para reconciliar ou executar ferramentas devem ter privilégios mínimos. Para modelos específicos, como GPT-6 Astra, e para integrações de uma organização como a OpenAI, a política final deve se ajustar ao contrato e às capacidades efetivamente documentadas para o endpoint utilizado.

A regra de encerramento é simples: não declare sucesso por ter emitido uma solicitação, nem declare ausência de efeito por não ter recebido uma resposta. Declare uma operação resolvida apenas quando a evidência persistida permitir sustentar seu estado. Quando essa evidência não existir, a decisão segura pode ser esperar, reconciliar ou pedir intervenção humana.

Continue a explorar

Correções e transparência

Se encontrar informação incorreta ou desatualizada, envie-nos a página e a fonte que devemos rever.