Tratamento de Erro

Identificadores de erros por nó no Fluxo que roteia falhas de nós para um caminho separado e expõem detalhes de erro por meio de variáveis.

O que é

O tratamento de erros no Fluxo é um mecanismo por nó que permite que você controle 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

Cada nó que é compatível com o tratamento de erros tem um identificador de erro — um conector de saída no canto inferior direito do nó que é ativado quando o nó falha. Nem todos os nós são compatíveis com o tratamento de erros; apenas aqueles com o sinalizador supportsErrorHandling expõem um identificador de erro.

Quando um nó com um identificador de erro conectado falha, a execução roteia 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 downstream.

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 .

NovasTentativas de solicitação HTTP

O nó de Solicitação HTTP é compatível com novas tentativas configuráveis. Quando novas tentativas são configuradas, o nó tenta a solicitação o número especificado de vezes antes de disparar o identificador de erro. Se todas as novas tentativas falharem e um identificador de erro estiver conectado, a execução roteará para o caminho do erro. Se nenhum identificador de erro estiver conectado, o processo falhará.

Configuração de identificadores de erro

Um identificador de erro é conectado conectando o conector do identificador de erro do nó (canto inferior direito) a outro nó na tela. Um nó sem um conector de identificador de erro não é compatível com o tratamento de erros; portanto, qualquer falha interrompe o processo.

O objeto de erro

Quando um identificador de erro é conectado e o nó falha, os detalhes do erro estão disponíveis $vars.<nodeName>.error. Este objeto tem os seguintes campos:

code

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

Mensagem

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

Detalhe

Uma descrição técnica detalhada da falha, incluindo rastreamentos 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. O acesso a $vars.<nodeName>.error no caminho do sucesso retorna um valor indefinido.

Exemplo prático

Este exemplo usa um nó HTTP Request para chamar uma API externa, com um nó Script no caminho do erro que registra a falha.

Um nó de Solicitação HTTP é colocado na tela e configurado com o URL de destino. Seu identificador de erro está conectado a um nó Script . O nó 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 o nó Script é ignorado. Quando a solicitação falha (após quaisquer novas tentativas configuradas), a execução roteia para o nó Script, que recebe o objeto de erro completo.

Padrões

Essas são abordagens comuns para tratamento, registro, novas tentativas e escalonamento de erros. Todos eles se baseiam no 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 $vars.<node>.error.

Registrar e continuar

Esse padrão se encaixa em operações não críticas onde o fluxo de trabalho deve continuar mesmo se uma etapa falhar. O identificador de erro do nó conecta-se a um nó do Script que registra o erro e, em seguida, reconecta 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 ajusta a falhas transitórias prováveis, como tempos limite 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 integradas repete 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 nova tentativa pertencem apenas a operações idempotentes.

Alertar e encerrar

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

Valor de fallback

Esse padrão se ajusta a operações que podem falhar, mas têm um valor padrão seguro que permite que o 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, retorna ao caminho principal como se a operação tivesse sido bem-sucedida.

Erros comuns

• Consumir erros silenciosamente — Erros no caminho de erros devem sempre ser registrados, mesmo quando o fluxo de trabalho continua. Falhas silenciosas são difíceis de diagnosticar posteriormente.
• Nova tentativa de operações não idempotentes — Operações com efeitos colaterais (escrita de dados, envio de uma mensagem) podem produzir duplicatas se forem repetidas. As configurações de nova tentativa devem ser apenas em 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 falha em todo o processo em caso de erro. Fluxos de trabalho que devem continuar após uma falha precisam de um caminho de erro conectado.

Páginas relacionadas

• Identificar erros — tarefa passo a passo: criar 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 Debug