Gestão de Erros e Exceções
O painel Gestão de Erros e Exceções da etapa: nova tentativa com intervalo, contorno a cada erro, contorno ao estourar o limite e encerramento controlado.
Nesta página
O painel Gestão de Erros e Exceções
Cada etapa tem, na aba Propriedades, o painel Gestão de Erros e Exceções. É ali que você define o que acontece quando a etapa falha e quanta falha o processo tolera:
| Campo | O que controla |
|---|---|
| Modo de Tratamento de Erros nesta Etapa | Sequencial ou Total. Decide o que acontece a cada erro antes do limite estourar. |
| Zerar a contagem quando a etapa passar | Decide como o limite conta: ligado, conta apenas erros seguidos; desligado, conta todos os erros daquela etapa na execução. |
| A cada erro | Só no modo Total: o contorno acionado em todo erro que ainda não estourou o limite. |
| Limite de Erros | Quantos erros desta etapa cabem antes do estouro. O limite conta erros: 3 significa que a etapa chega a executar 3 vezes. Zero é sem limite. |
| Intervalo entre Tentativas | Quantos segundos esperar antes de cada nova tentativa. Zero é uma escolha válida e significa tentar de novo na hora. Só aparece quando a configuração de fato repete a etapa, ou seja, no modo Sequencial e nos contornos que terminam em "e retentar". |
| Ao estourar o limite | O que fazer quando o Limite de Erros é atingido: terminar o processo, ir para uma etapa ou seguir para a próxima. |
Os dois estágios de um erro
Quando uma etapa falha (elemento não encontrado, timeout, erro de rede), o erro passa por dois estágios. O primeiro vale enquanto o Limite de Erros não estourou; o segundo, quando estoura.
Script que estoura o tempo também é um erro de etapa.
Numa etapa de Regra Customizada, quando o script passa do Limite de Tempo do Script, ele é encerrado e a etapa entra exatamente neste mesmo fluxo: nova tentativa, contorno, limite. É o que transforma um script travado em nova tentativa, em vez de uma execução parada até alguém perceber. Para isso funcionar, o limite precisa ser coerente com o trabalho da etapa: com um tempo folgado demais, a reação só acontece horas depois.
| Sequencial | Total | |
|---|---|---|
| A cada erro | Espera o Intervalo entre Tentativas e tenta a mesma etapa de novo. Não há escolha: o modo é retentativa pura. | Aciona o contorno do campo A cada erro, que pode ser um desvio ou uma ação na página. |
| Ao estourar | Aciona o contorno do campo Ao estourar o limite: terminar o processo, ir para uma etapa ou seguir para a próxima. | |
| Contador | Independente do modo: zera quando a etapa passa se Zerar a contagem quando a etapa passar estiver ligado, e nunca zera se estiver desligado. | |
Qual modo escolher
Se tentar de novo já resolve, use Sequencial. Se antes de tentar de novo é preciso fazer alguma coisa, como passar por outras etapas que reconstroem a sessão ou registram o ocorrido, use Total: é ele que oferece o contorno a cada erro.
O que o contorno "A cada erro" oferece
Disponível apenas no modo Total. As opções com "e retentar" no nome repetem a etapa e respeitam o Intervalo entre Tentativas; as outras seguem o fluxo na hora, e por isso o campo de intervalo nem aparece quando você escolhe uma delas. As seis opções que agem na própria página (recarregar, voltar, avançar, passar o mouse, focar e pressionar tecla) levam no menu o complemento - Para navegadores, porque só fazem sentido em etapa de navegador.
| Opção | Comportamento |
|---|---|
| Seguir para a próxima etapa | Registra o erro, conta contra o limite e deixa o fluxo continuar, como se a etapa tivesse passado. Se a etapa for a última de uma rota de decisão, o fluxo vai para o ponto de junção, e não para a rota seguinte. |
| Ir para determinada Etapa | Desvia o fluxo para a etapa escolhida. É o caminho de saída: permite uma rota de recuperação que conserta o estado e devolve o fluxo. |
| Recarregar e retentar | Recarrega a página, espera o intervalo e tenta a mesma etapa de novo. |
| Voltar e retentar / Avançar e retentar | Anda no histórico do navegador, espera o intervalo e tenta de novo. |
| Passar o mouse, Focar ou Pressionar tecla e retentar | Executa a ação no seletor ou tecla informada, espera o intervalo e tenta a mesma etapa de novo. Serve para revelar um elemento que só aparece sob interação. |
| Terminar o processo | Encerra na hora, sem esperar o limite. |
Ação "Para navegadores" em etapa sem navegador
Recarregar, Voltar, Avançar, Passar o mouse, Focar e Pressionar tecla agem na página aberta. Em uma etapa de Chamar API Rest, de Conector ou de Regra Customizada, elas só acontecem se uma etapa anterior já tiver aberto uma página, e nesse caso agem sobre ela. Se não houver nenhuma página aberta na execução, a ação é pulada: o log registra um aviso e a etapa é tentada de novo normalmente, respeitando o Intervalo entre Tentativas e o limite de erros. Para etapas que não usam navegador, prefira Ir para determinada Etapa, que refaz o que for preciso antes de devolver o fluxo.
O que o contorno "Ao estourar o limite" oferece
Vale nos dois modos. Não há opção de retentar aqui: no estouro, retentar é justamente o que acabou de ser interrompido.
| Opção | Comportamento |
|---|---|
| Terminar o processo | Encerra com erro. É o padrão. |
| Ir para determinada Etapa | Desvia para uma etapa de tratamento, como registrar a falha e notificar alguém antes de encerrar de forma controlada. |
| Seguir para a próxima etapa | Desiste desta etapa e deixa o fluxo continuar. Use só quando a falha puder ser ignorada com segurança. |
Etapas configuradas antes desta mudança
Elas continuam executando exatamente como sempre executaram. Ao abrir uma delas no Agent Builder, o painel mostra um aviso e já exibe os campos novos preenchidos com o equivalente ao que a etapa faz hoje. A conversão só passa a valer quando você salvar, e você vê o resultado antes de confirmar.
Limite de Erros e Contagem
O Limite de Erros é configurado por etapa: cada etapa tem seu próprio contador de falhas, independente de qualquer outra etapa do processo. Quem decide como esse contador é somado é o campo Zerar a contagem quando a etapa passar, e ele vale nos dois modos de tratamento:
| Zerar no sucesso | Como conta | Quando usar |
|---|---|---|
| Ligado (conta seguidos) | O contador zera sempre que a etapa é executada com sucesso, então só uma sequência de falhas seguidas chega ao limite. | Loops que processam listas (mesma etapa repetida a cada iteração): itens isolados podem falhar, mas uma sequência de falhas seguidas indica problema real, como sistema fora do ar ou sessão perdida. |
| Desligado (conta todos) | O contador nunca zera: soma todos os erros daquela etapa na execução, mesmo intercalados com sucessos. | Orçamento de qualidade: se a etapa falhou N vezes no total, mesmo tendo se recuperado de cada uma, alguma coisa está errada com o lote e vale parar. |
O limite conta erros, não tentativas extras
Limite 3 com intervalo de 10 segundos, em modo Sequencial: a etapa executa, falha, espera 10 segundos, executa de novo, falha, espera mais 10, executa a terceira vez e falha. Esse terceiro erro é o estouro, e aí entra o contorno do estouro. Três execuções, duas esperas.
Exemplo em loop
Limite 10 em modo Sequencial, numa etapa dentro de um loop de 200 itens: a etapa pode acumular dezenas de falhas isoladas ao longo do loop sem estourar, mas 10 falhas seguidas dessa mesma etapa estouram. Em modo Total, o 10º erro dessa etapa estoura, não importa quando aconteceu.
Zero é sem limite
Com Limite de Erros em zero a etapa nunca estoura por conta própria, e o contorno do estouro nunca é acionado. Em modo Sequencial isso significa retentar indefinidamente. O teto passa a ser o Limitador de Ações e o Limitador de Exceções do cadastro do agente. Etapas novas já nascem com limite 3 e intervalo de 5 segundos.
Uma vez estourado, o limite não volta a zero
O contador do modo Total nunca zera, e o do Sequencial só zera quando a própria etapa é executada com sucesso. Então, depois que o Limite de Erros estoura, ele fica estourado pelo resto da execução: se o fluxo voltar para aquela etapa, seja pelo contorno do estouro, por uma rota ou por um
Isso torna possível montar um ciclo sem saída: a etapa falha, o contorno manda para outro lugar, o fluxo volta, ela falha de novo. Quem interrompe é o Limitador de Ações do agente, e a execução termina com status TERMINATED depois de gastar todo o orçamento de ações, gravando uma evidência a cada volta. Se você precisa reprocessar a etapa depois de consertar o estado, condicione o retorno: use uma rota que só devolva o fluxo quando a causa do erro tiver mudado, em vez de devolver incondicionalmente.
goto(), ela chega sem orçamento e o primeiro erro já aciona o contorno do estouro de novo.
Isso torna possível montar um ciclo sem saída: a etapa falha, o contorno manda para outro lugar, o fluxo volta, ela falha de novo. Quem interrompe é o Limitador de Ações do agente, e a execução termina com status TERMINATED depois de gastar todo o orçamento de ações, gravando uma evidência a cada volta. Se você precisa reprocessar a etapa depois de consertar o estado, condicione o retorno: use uma rota que só devolva o fluxo quando a causa do erro tiver mudado, em vez de devolver incondicionalmente.
Por etapa, não pelo processo inteiro
Se duas etapas diferentes falharem algumas vezes cada uma, sem que nenhuma isoladamente atinja seu próprio Limite de Erros, o processo continua, porque os contadores não se somam entre etapas. Para um teto único que soma erros de qualquer etapa do processo, use o Limitador de Exceções do cadastro do agente (Cadastro do Agente). Esse é global, nunca zera, prevalece sobre a configuração da etapa e serve como rede de segurança final.
Padrão: nova tentativa
Para uma etapa que falha de forma intermitente, como login em sistema instável ou API com timeout eventual, não é preciso montar nada: basta configurar o painel.
| Campo | Valor |
|---|---|
| Modo de Tratamento de Erros nesta Etapa | Sequencial |
| Zerar a contagem quando a etapa passar | SIM (conta apenas erros seguidos) |
| Limite de Erros | 3 (a etapa chega a executar 3 vezes) |
| Intervalo entre Tentativas | 10 segundos |
| Ao estourar o limite | Ir para determinada Etapa → uma etapa de tratamento, ou Terminar o processo |
Se a etapa passar em qualquer uma das tentativas, o fluxo segue normalmente e o contador zera. Se as três falharem, entra o contorno do estouro.
E se tentar de novo não bastar
Quando a página precisa ser consertada antes da nova tentativa, troque o modo para Total e use o campo A cada erro. Com Recarregar e retentar, cada erro recarrega a página antes de repetir a etapa. Com Ir para determinada Etapa, cada erro desvia para uma rota que refaz o login, limpa o estado ou registra o ocorrido, e depois devolve o fluxo.
Evidência e aviso de falha
Numa rajada de tentativas, a evidência em PDF e o e-mail de falha saem no primeiro erro, que é o retrato de como quebrou, e no estouro. As tentativas do meio não repetem os dois, mas cada uma registra sua linha de log com a mensagem do erro.
Sem imagem quando há dado sensível
A evidência automática de falha é o retrato da tela, e uma imagem não tem como esconder um dado em partes. Por isso, quando a etapa ou a execução lida com dado sensível, a imagem não é gerada. O erro continua sendo registrado com a mensagem e a etapa, e os valores marcados aparecem como
«•••».
Padrão: Capturar e Registrar
Quando um erro não impede o processo de continuar, mas deve ser registrado para análise posterior:
Capturar falha e continuar o lote
// Etapa: Processar Item
// Modo Total · "A cada erro" → Ir para a Etapa → Registrar Falha do Item
// Etapa: Registrar Falha do Item (Regra Customizada)
const item = bm.get('{item_atual}');
const falhas = bm.get('{falhas}', []);
falhas.push(item);
bm.bmLog('[FALHA] Item ' + item + ' não processado');
bm.done('registrou', {
'{falhas}': falhas
});
// Continua normalmente para a próxima etapa do loopAo final do processo, a variável {falhas} contém a lista de itens que falharam, disponível para envio por e-mail ou salvar em planilha.
Encerramento Gracioso
Quando uma falha crítica deve encerrar o processo, mas antes disso vale montar um relato do que aconteceu e notificar alguém, em vez de só deixar o Limitador de Exceções encerrar sozinho, sem contexto:
Etapa crítica "Acessar Sistema" → Preparar Notificação → Gmail → Encerrar
// Etapa crítica: "Acessar Sistema"
// "Ao estourar o limite" → Ir para a Etapa → Preparar Notificação
// Etapa: Preparar Notificação (Regra Customizada)
const relatorio =
'Processo ' + bm.get('{processName}') + ' falhou na etapa ' + bm.get('{errorStep}') + '.\n' +
'Erro: ' + bm.get('{errorDescription}') + '\n' +
'Último item processado: ' + bm.get('{item_atual}', 'nenhum');
bm.done('preparou', { '{relatorio_erro}': relatorio });
// Etapa: Notificar Falha (Conectar Serviços → Gmail)
// Corpo do e-mail referencia {relatorio_erro}
// "Ao estourar o limite" → Seguir para a próxima (encerra mesmo se o e-mail falhar)
// Etapa: Encerrar com Erro (Decisão 🔷)
// Rota 1: true → terminate()"Preparar Notificação" monta o texto a partir das variáveis de erro do sistema e grava em {relatorio_erro}; a etapa Conectar Serviços seguinte só precisa referenciar essa variável no corpo do e-mail, sem repetir a lógica de montagem em cada processo.
Isso é um relatório ad hoc, escrito por você. Para alertas automáticos sem montar nada no fluxo, configure o campo Enviar e-mail quando: do cadastro do agente.