O passo Em caso de erro e o Pré-processador

Dois cartões acima do canvas

No canto superior esquerdo do canvas ficam dois cartões discretos: Em caso de erro (“Roda se um passo falhar — para avisar alguém.”) e Pré-processador (“Transforma a chamada da API nas entradas do fluxo.”). Vazio, cada um mostra Adicionar. Depois de definido, o cartão mostra o logo e o nome do passo — clique para abrir o passo, e em ⋯ para remover. Numa execução, o cartão mostra o status do passo só quando ele de fato rodou.

Nenhum dos dois tem ligações, e nada na cadeia pode se ligar a eles. É de propósito: eles respondem a eventos — uma falha, uma chamada de API — e não a uma posição no flow.

Adicione um passo Em caso de erro

1. 1
   Escolha o que ele é

   Clique em Adicionar no cartão Em caso de erro. Em Escrever código, escolha Python, TypeScript ou JavaScript (“Roda com o erro: a mensagem, qual passo falhou…”); em Ou, escolha E-mail (“Envia um e-mail dizendo o que falhou”) ou Subflow (“Roda outro fluxo com o erro”).

2. 2
   Leia o erro

   O painel do passo abre em O que este passo pode ler: error.message, error.stepName, error.stepId, error.code e error.name. Use esses valores numa entrada do tipo Expression — clique em um para copiar. Um passo de script novo já chega ligado: message ← error.message e step ← error.stepName.

3. 3
   Mande para algum lugar

   Um passo de e-mail liga o erro nos valores do template; um subflow repassa o erro para um flow que você reutiliza em vários flows. Scripts não têm rede, então para chegar numa ferramenta de chat use um e-mail ou um subflow com um passo Requisição HTTP.

def main(message: str = "", step: str = ""):
    print(f"{step} failed: {message}")

Charge card failed: card declined

Quando ele roda

A execução continua com falha e com o erro original: faça o que fizer o passo Em caso de erro, e mesmo que ele próprio falhe, o status e o erro da execução são os do passo que falhou. No canvas ele mostra Rodou porque o flow falhou. Os alertas do projeto são separados e disparam pelas próprias regras; use o passo Em caso de erro para o que é específico deste flow.

O Pré-processador

Quando um flow é publicado como endpoint de API, quem chama decide o formato da requisição — um webhook de uma loja manda o próprio JSON. O Pré-processador adapta isso. Ele é um script (Python, TypeScript ou JavaScript) cujo main(request) recebe method, path, query, headers, rawBody e body (lido de JSON ou formulário) e deve devolver um objeto: esse objeto vira as entradas do flow, como se tivessem sido digitadas no Início.

def main(request: dict):
    # request: method, path, query, headers, rawBody, body
    body = request.get("body") or {}
    return {
        "orderId": body.get("order", {}).get("id"),
        "source": request["query"].get("source", "api"),
    }

• Ele roda só em chamadas por endpoint de API. Execuções pelo editor, por agendamento ou por outro flow o ignoram.
• O endpoint não faz mapeamento de parâmetros para esse flow — a requisição inteira vai para o Pré-processador.
• Testar com uma requisição salva roda o código atual com uma das chamadas recentes do flow e mostra Entradas produzidas. Sem chamadas ainda, aparece Nenhuma chamada ainda — chame o endpoint do flow uma vez.
• A requisição de cada chamada ao endpoint fica guardada com a execução por 30 dias (bodies de até 1 MB), e a execução pode ser refeita com ela.

Regras e códigos de erro

• Um passo Em caso de erro por flow (on_error_duplicate) e um Pré-processador (preprocessor_duplicate).
• O passo Em caso de erro é um script, um e-mail ou um subflow, e não pode usar Continuar mesmo com erro. O Pré-processador é um script e não pode ser também o passo Em caso de erro.
• Um Pré-processador que lança erro, estoura o tempo ou devolve algo que não é objeto faz a execução falhar com preprocessor_failed.