Tratamento de Erro

Manipuladores de erro por nó no Fluxo que roteiam as falhas de nó para um caminho separado e expõem os detalhes do erro por meio de variáveis.

O que é

O tratamento de erros no Fluxo é um mecanismo por nó que permite controlar o que acontece quando um nó falha durante a execução. Por padrão, um nó com falha interrompe todo o processo. Você pode substituir isso conectando um identificador de erro para rotear falhas para um caminho separado, onde você inspeciona e responde ao erro.

Como funciona

Every node that supports error handling has an error handle — an output connector on the bottom-right of the node that activates when the node fails. The majority of nodes support error handling.

Quando um nó com um identificador de erro conectado falha, a execução é roteada para o caminho do erro em vez de interromper o processo. Os detalhes do erro ficam disponíveis como uma variável que você pode ler em nós subsequentes.

Quando um nó sem um identificador de erro conectado falha, todo o processo falha imediatamente. O erro aparece no painel de execução na guia Incidentes.

Novas tentativas de solicitação HTTP

O nó de Solicitação HTTP oferece suporte a novas tentativas configuráveis. Quando novas tentativas são configuradas, o nó tenta solicitar o número de vezes especificado antes de disparar o identificador de erro. Se todas as NovasTentativas falham e um identificador de erro estiver conectado, a execução roteia para o caminho do erro. Se você não conectar nenhum identificador de erro, o processo falhará.

Configuração de identificadores de erro

Um identificador de erro é conectado ligando o conector de identificador de erro do nó (canto inferior direito) a outro nó na tela. Um nó sem um conector de identificador de erro não oferece suporte ao tratamento de erros, portanto qualquer falha interrompe o processo.

O objeto de erro

Quando você conecta um identificador de erro e o nó falha, os detalhes do erro estão disponíveis como $vars.<nodeName>.error. Esse objeto tem os seguintes campos:

code

Um código de erro legível por máquina identificando o tipo de falha.

Mensagem

Uma descrição legível por humanos do que deu errado. Use isso para registro ou exibir informações de erro.

Detalhe

Uma descrição técnica detalhada da falha, incluindo traces de pilha ou informações específicas do serviço quando disponíveis.

categoria

A categoria de erro, agrupando tipos de erro relacionados.

status

O código de status HTTP associado ao erro. Preenchido para falhas relacionadas a HTTP (por exemplo, 404 ou 500).

O objeto de erro está disponível apenas no caminho do erro. Acessar $vars.<nodeName>.error no caminho do sucesso retorna undefined.

Exemplo prático

Este exemplo usa um nó de Solicitação HTTP para chamar uma API externa, com um nó de Script no caminho de erro que registra a falha.

Um nó de Solocitação HTTP é colocado na tela e configurado com a URL de destino. Seu identificador de erro está conectado a um nó de Script. O nó do Script lê o objeto de erro da seguinte forma:

const error = $vars.httpRequest1.error;
return {
  failed: true,
  reason: error.message,
  httpStatus: error.status,
  detail: error.detail
};

Quando a solicitação HTTP é bem-sucedida, a execução segue o caminho de sucesso e ignora o nó do Script. Quando a solicitação falha (após quaisquer novas tentativas configuradas), a execução roteia para o nó do Script, que recebe o objeto de erro completo.

Padrões

Essas são abordagens comuns para tratar, registrar, tentar novamente e escalonar erros. Todos eles têm como base o identificador de erro por nó descrito acima: um identificador de erro conectado roteia falhas para um caminho separado, onde o objeto de erro está disponível em $vars.<node>.error.

Registrar e continuar

Esse padrão se aplica a operações não críticas em que o fluxo de trabalho deve continuar mesmo se uma etapa falhar. O identificador de erro do nó se conecta a um nó de Script que registra o erro e, em seguida, ele volta ao caminho principal para que a execução continue.

// Script node on the error path
console.log('Non-critical step failed:', $vars.step1.error.message);
return null; // downstream nodes handle null gracefully

Tentar novamente com limite

Esse padrão se adapta a prováveis falhas transitórias, como tempos limites de rede, limites de taxa ou interrupções temporárias de serviço. Para o nó de Solicitação HTTP, a contagem de novas tentativas integrada tenta novamente a solicitação antes de disparar o identificador de erro, e apenas a falha final roteia para o caminho do erro. As configurações de novas tentativas pertencem apenas às operações idempotentes.

Alertar e encerrar

Esse padrão é adequado para erros irrecuperáveis que exigem atenção humana. No caminho de erro, uma notificação é enviada (por meio de uma Solicitação HTTP ou nó de integração), em seguida, um nó de Encerrar com status Failed e uma mensagem descritiva, como $vars.step1.error.message, encerra o fluxo de trabalho.

Valor de fallback

Este padrão é ideal para operações que podem falhar, mas possuem um valor padrão seguro que permite que o seu fluxo de trabalho continue de forma significativa. No caminho de erro, um nó de Script define a saída esperada como um valor padrão e, em seguida, retoma o caminho principal como se a operação tivesse sido bem-sucedida.

Erros comuns

• Ignorar erros silenciosamente — Erros no caminho de erro devem sempre ser registrados, mesmo quando o fluxo de trabalho continua. Você terá dificuldade em diagnosticar falhas silenciosas mais tarde.
• Tentar novamente operações não idempotentes — Operações com efeitos colaterais (gravação de dados, envio de uma mensagem) podem produzir duplicatas se repetidas. Configurações de novas tentativas pertencem apenas a operações que podem ser executadas mais de uma vez sem criar duplicatas.
• Deixar identificadores de erro desconectados — Um nó cujo identificador de erro não está conectado faz com que todo o processo falhe em caso de erro. Os fluxos de trabalho que devem continuar após uma falha precisam de um caminho de erro conectado.

Páginas relacionadas

• Lidar com erros — Tarefa passo a passo: crie um caminho de erro de ponta a ponta
• A tela — visão geral do espaço de trabalho, incluindo o painel de execução
• Variáveis e fluxo de dados — como os dados passam entre nós usando $vars
• Depuração eficaz — dicas para inspecionar erros no modo de Debug