Uma automação falhou: o que verificar antes de tentar novamente

Uma automação indica erro e alguém propõe clicar em «Tentar novamente». Antes, convém responder a uma pergunta mais específica: o que falta fazer? Pode faltar a ação, sua confirmação ou um passo posterior. Repetir o fluxo completo serve para uma dessas situações e pode piorar as outras.

Para um fundador ou uma equipe pequena, a investigação deve poder continuar mesmo que a pessoa que montou a integração não esteja presente. Este guia apresenta uma cronologia e uma ficha para distinguir o que foi verificado do que é desconhecido. O exemplo é fictício: não descreve um incidente da Frihet nem utiliza serviços, clientes ou credenciais reais.

O erro da tela e o status do trabalho

Um timeout indica que uma espera terminou sem resposta a tempo. Por si só, não permite saber se o destino salvou algo. A AWS explica este problema com uma solicitação que poderia ter criado um recurso mesmo que o solicitante não recebesse a confirmação. Resolver essa incerteza exige identificar o efeito e sua origem.

Trabalhe com três status: efeito confirmado, ausência de efeito confirmada e desconhecido. «Não aparece na minha tela» pertence ao terceiro enquanto puder haver filtros, outra conta, um índice atrasado ou uma execução ainda ativa. Anote também quem verificou o status e a que horas: uma observação tem contexto, não validade eterna.

Uma cronologia que muda a decisão

Suponhamos um fluxo que cria uma tarefa interna e depois registra sua referência em uma planilha de acompanhamento. Tudo o que se segue é hipotético. Os tempos usam o mesmo relógio simulado; em uma investigação real, preserve o fuso horário e a origem de cada registro de horário.

O próximo passo é completar apenas o registro pendente na planilha, seguindo o procedimento documentado. Reiniciar a partir de «criar tarefa» repetiria uma ação já concluída. Se a última linha apenas dissesse «não vejo na planilha», ainda teríamos que descartar um atraso, um filtro ou um processo ativo antes de escrever ali.

A referência de operação permanece estável; o identificador de tentativa muda a cada execução. Um evento recebido e uma tarefa criada também têm identidades distintas. Preserve suas relações para não confundir duas tentativas de um mesmo trabalho com dois trabalhos legítimos.

Guarde uma ficha que outra pessoa possa continuar

Comece por preservar os registros existentes e conter novas escritas com o mecanismo de pausa previsto para esse fluxo. Uma pausa não desfaz o que foi executado nem garante parar solicitações que já estão em curso. Revise a fila e as tentativas pendentes antes de assumir que ninguém mais agirá.

Copie esta ficha em um registro interno com acesso adequado. Use referências a evidências, evitando colar segredos ou dados pessoais em documentos compartilhados. Cada correção deve ser adicionada com data, sem apagar a observação anterior.

Incidente: [referência interna]
Operação desejada: [um único resultado concreto]
Provedor / conta / ambiente: [contexto do destino]
Operação / evento / tentativas: [IDs e relações]
Versão do fluxo: [versão executada]
Último passo confirmado: [evidência e hora com fuso horário]
Status do efeito: [efeito confirmado / ausência de efeito confirmada / desconhecido]
Evidência do destino: [referência, consulta e limites de visibilidade]
Trabalho ainda ativo: [solicitações, fila e tentativas pendentes]
Regras de nova tentativa: [documentação, escopo e prazo de validade]
Dado que falta: [prova necessária para decidir]
Próxima ação: [consulta ou recuperação limitada]
Responsável / próxima revisão: [pessoa e data]
Resultado posterior: [nova evidência, sem sobrescrever a anterior]

«Ausência de efeito confirmada» precisa de uma prova mais forte do que uma busca vazia: por exemplo, uma rejeição prévia à execução documentada pelo destino, com as demais tentativas descartadas como possível origem do efeito. Se você não puder justificar esse status, mantenha «desconhecido».

A chave de idempotência tem limites

Verifique o contrato do provedor para a solicitação específica, conta e ambiente. Uma chave que protege uma escrita não protege automaticamente uma notificação posterior nem outro serviço. Tampouco pode ser adicionada retroativamente a uma solicitação que já foi enviada sem ela. A ficha deve incluir um link para a documentação aplicável, não apenas dizer «temos idempotência».

No Stripe, as solicitações idempotentes — API v1 reutilizam o resultado salvo da primeira execução, incluindo erros 500. O Stripe compara parâmetros e pode remover chaves após pelo menos 24 horas; reutilizar uma chave removida inicia outra solicitação. Seu guia de erros adverte sobre possíveis efeitos após um 500: mudar a chave ou esperar que ela expire não demonstra que seja seguro repetir uma ação cujo resultado ainda é incerto.

O prazo citado é específico do Stripe. Para outro destino, anote sua própria janela, a identidade que considera repetida e o tratamento das solicitações concorrentes. Se uma recuperação exigir a mudança de parâmetros, trate-a como uma nova decisão, com revisão dos efeitos anteriores.

Decida com base na evidência, passo a passo

A tabela a seguir é um critério operacional proposto, não uma política universal do provedor. Separa a investigação da autorização para modificar dados.

As escritas irreversíveis ou de alto impacto precisam de revisão humana da recuperação proposta. Nem uma chave nem um botão verde oferecem uma garantia de «exatamente uma vez» para todo o percurso.

Verifique também quem tentará novamente

A ferramenta de automação, o cliente de API e o provedor podem ter mecanismos próprios de novas tentativas. Nos webhooks do Stripe, um reenvio manual não cancela as tentativas automáticas; além disso, eventos podem se repetir e chegar fora de ordem. Reenviar um evento também não equivale a repetir de forma idempotente uma escrita de API: são mecanismos distintos.

Antes de fechar a ficha, verifique o status atual do destino, os passos pendentes e as tentativas que poderiam chegar depois. Defina quem observará a próxima execução. Fechar a ficha não equivale a resolver o trabalho: se sobrar um resultado desconhecido, mantenha o incidente aberto com responsável e data de revisão.

Depois, você pode revisar se o fluxo merece continuar automatizado com o critério de eliminar, automatizar e delegar (em inglês). Se o fluxo se conecta à Frihet, consulte a documentação para desenvolvedores e o catálogo de integrações para localizar a interface correspondente. Preserve esta ficha junto ao fluxo: a próxima pessoa deve conseguir encontrar o último status verificado sem reconstruí-lo a partir de um chat.

Fontes técnicas consultadas em 14 de setembro de 2026. As fichas, decisões e referências DEMO são propostas didáticas próprias; não são instruções para executar mudanças em um serviço real.