🔐 Disponível para clientes com o add-on de Custom Integrations
👤 Para quem opera e mantém flows de integração em produção
🎯 Nível: intermediário
Flows de integração falham. APIs ficam indisponíveis, payloads chegam em formato inesperado, credenciais expiram, volumes acima do esperado geram timeouts. O problema não é que falhas aconteçam: é não saber onde olhar quando acontecem. Sem um método de diagnóstico, o time perde tempo testando hipóteses aleatórias enquanto o processo fica parado.
Este artigo apresenta o método de diagnóstico do Integrações Pipefy: onde encontrar o que quebrou, como interpretar os sinais que a plataforma dá e como decidir qual correção aplicar.
📖 O que você vai entender aqui:
Por onde começar: o painel de execuções
Toda execução de flow gera uma execução com seu próprio id. O painel de execuções é o ponto de entrada para qualquer diagnóstico: ele lista todas as execuções com status de sucesso, falha, enfileiradas, ordenadas por tempo. Uma falha que o time reportou "agora" tem uma execução correspondente com data e hora, e nessa execução tem tudo que é necessário para entender o que aconteceu.
Cada execução detalha a sequência de passos executados, os dados que entraram em cada passo, os dados que saíram e, quando há falha, o erro aparecerá como resultado retornado pelo sistema. O erro está sempre num passo específico. Identificar qual passo falhou é a primeira ação a ser feita no processo de diagnóstico: a causa está ali ou imediatamente antes, num dado incorreto que aquele passo recebeu.
O step com falha raramente é o problema real. Na maioria dos casos, o problema é o dado que chegou até ele. Antes de investigar a configuração do step que falhou, examine os dados de saída do step anterior. Dado errado na entrada produz erro na saída.
Lendo códigos HTTP: o que cada faixa indica
Quando o step que falhou é uma chamada a uma API externa, o código de status HTTP da resposta é o diagnóstico mais rápido disponível. Cada faixa de código corresponde a uma classe de problema com uma ação de correção diferente.
2xx: a chamada funcionou
Códigos entre 200 e 299 indicam que a API recebeu e processou a requisição corretamente. Se o flow ainda assim não entregou o resultado esperado, o problema está no mapeamento dos dados de resposta, não na chamada em si. Verifique se o campo que o passo seguinte espera está de fato presente no payload retornado.
4xx: o problema está na requisição
400 indica que a API rejeitou a requisição por dados incorretos ou ausentes. Revise o payload enviado: campos obrigatórios faltando, tipos de dados errados, formatos inválidos. 401 e 403 são erros de autenticação e autorização. O token expirou, a chave de API está incorreta ou a Service Account não tem permissão para a operação solicitada. 404 indica que o recurso não foi encontrado: o ID passado não existe, a URL está errada ou o registro foi removido. 429 indica que o limite de requisições da API foi atingido. O flow está chamando a API rápido demais e precisa de controle de taxa.
5xx: o problema está no servidor externo
Códigos 500 a 599 indicam que o sistema externo falhou ao processar a requisição por razões internas. O problema não está no flow. A ação imediata é verificar o status da API com o provedor e tentar novamente após o sistema se recuperar. Retry automático com intervalo é a resposta correta para 5xx transitórios.
429 e 503 têm comportamentos parecidos na superfície: o flow falha e a API não responde como esperado. A diferença importa na correção. 429 exige reduzir a frequência das chamadas ou distribuir o volume ao longo do tempo. 503 exige aguardar a recuperação do servidor externo. Tratar os dois da mesma forma cria flows que continuam agredindo uma API com rate limit ou que ficam em retry loop numa API indisponível.
Caso de uso: diagnóstico de uma execução com falha (FAILED) numa chamada externa (Pipefy × ERP)
Nem toda falha deve ser escondida. Quando uma integração depende de um sistema externo, a falha precisa aparecer para que a pessoa que opera o fluxo saiba exatamente o que corrigir. Este caso de uso mostra um flow que falha de propósito num cenário real, e ensina a ler esse FAILED na aba de execuções no Integrações Pipefy, usando o diagnóstico mais rápido que existe: o código de status HTTP.
O cenário
Um card é criado no Pipefy representando uma fatura aprovada. O fluxo então registra essa fatura no ERP da empresa via uma chamada HTTP e, no retorno, atualiza o próprio card com a referência gerada pelo ERP.
O ponto frágil, e é assim em qualquer integração, é a chamada externa. O ERP pode rejeitar o dado, exigir reautenticação, estar fora do ar ou aplicar rate limit. Quando isso acontece, o passo HTTP falha, o passo seguinte não roda, e a execução inteira é marcada como FAILED na aba de Execuções. É esse FAILED que vamos aprender a interpretar.
Por que esse run aparece como FAILED (e por que isso é bom)
No passo HTTP, deixamos Continue on Failure desligado. Isso é proposital: quando a chamada ao ERP falha, queremos que a execução pare e seja sinalizado como FAILED, em vez de seguir adiante fingindo que deu certo. Uma falha visível é uma falha que pode ser corrigida; uma falha silenciosa vira problema do financeiro semanas depois.
Mantivemos Retry on Failure ligado para absorver instabilidades passageiras (um 5xx ou 429 transitórios se resolve sozinho). Mas se os retries se esgotam, ou se o erro é do tipo que retry nenhum resolve (um 4xx), o run vai a FAILED, e aí entra o diagnóstico humano.
Como analisar o run FAILED na aba de Runs
- Abra a aba Execuções e filtre por status FAILED.
- Clique na execução e flow com falha. O produto destaca o passo que falhou (em vermelho) — neste caso, o POST fatura no ERP.
- Abra o output desse passo. Ali estão a errorMessage e, o mais importante numa chamada HTTP, o código de status da resposta.
- Leia o código pela faixa e aplique a ação de correção correspondente. Não saia reexecutando às cegas, o código diz se faz sentido tentar de novo ou se é preciso corrigir algo antes.
Recomendações e boas práticas
- Configure o retry pela classe do erro. Retry on Failure é certo para 5xx/429 transitórios, mas não corrige 4xx, para erros de requisição, o caminho é ajustar o dado, não repetir a chamada. Se quiser tratamento fino, capture o status usando o Error handling.
- Para 429, controle a taxa, não a insistência. Distribua o volume (fracionamento, delay entre chamadas) em vez de só tentar de novo mais rápido.
- Trate a execução como idempotente — para que reexecutar seja seguro. Este é o ponto que amarra tudo. Quando você executa uma execução com status FAILED (ou quando o retry automático dispara), os efeitos colaterais de uma chamada que chegou a ser processada antes de a resposta se perder podem ser reaplicados. Por isso a chamada ao ERP carrega uma Idempotency-Key (aqui, o número da NF): o ERP reconhece a chave e, num reenvio, devolve o registro já existente em vez de criar um segundo. Do lado do Pipefy, o mesmo princípio vale, antes de criar um card, busque pela chave única (padrão search-before-create). Assim, diagnosticar e reexecutar nunca gera duplicidade.
Falha transitória ou falha estrutural: a distinção que define a correção
Nem toda falha exige mudança no flow. Muitas falhas em produção são transitórias: o sistema externo estava momentaneamente indisponível, a rede teve instabilidade, o rate limit foi atingido por um pico de volume não usual. Nesses casos, o flow está correto e a correção é simplesmente reprocessar a execução após a condição externa se resolver, usando as opções de reexecução que o produto oferece.
Falhas estruturais têm um padrão diferente: o mesmo tipo de erro aparece de forma consistente, em múltiplas execuções, com os mesmos dados de entrada. Um campo que chega sempre vazio, um mapeamento que produz sempre um tipo de dado errado, uma condição no Router que nunca é verdadeira. Nesses casos, reprocessar não resolve: o flow precisa ser corrigido antes do retry.
Reprocessar um run com Retry on Latest Version quando o problema era transitório e nenhuma alteração foi feita no flow cria uma execução duplicada com risco de dados duplicados no sistema destino: dois registros criados, dois e-mails enviados, dois updates aplicados. Use Retry from Failed Step para falhas transitórias. Use Retry on Latest Version somente após corrigir o flow.
Práticas que reduzem o tempo de diagnóstico
Troubleshooting eficiente em produção começa na fase de construção. Flows bem construídos são mais fáceis de diagnosticar porque deixam rastros claros de onde e por que falharam.
- Documente cada step com comentários. Nome do sistema que está sendo chamado, propósito da chamada, estrutura esperada de entrada e saída. Um passo sem contexto é um passo que leva dez minutos para entender durante um diagnóstico sob pressão.
- Trate dados ausentes explicitamente. Um Router que verifica se um campo existe antes de usá-lo não só protege o flow de falhas: ele também localiza exatamente onde o dado ausente foi detectado, o que acelera o diagnóstico quando o problema é upstream.
- Use nomes descritivos para os passos. "Criar registro no ERP Jurídico" é o diagnóstico imediato no painel de Execuções. "HTTP 2" não é.
- Nunca armazene credenciais diretamente no código ou em campos de texto da configuração. Credenciais expiram, mudam e precisam ser atualizadas em um lugar só. Use sempre conexões autenticadas ou a opção de Variáveis do Integrações Pipefy.
Checklist de conclusão
☐ Por onde começar o diagnóstico quando um flow falha em produção
☐ O que cada faixa de código HTTP indica e qual ação ela pede
☐ A diferença entre falha transitória e falha estrutural, e como cada uma impacta a escolha do retry
☐ Por que documentar steps durante a construção reduz o tempo de diagnóstico
