Monitoramento e solução de problemas de Flows

Onde acompanhar execuções, como ler uma execução com falha até o nó que quebrou e as cinco falhas que você realmente encontrará: sintoma, causa e a correção que você mesmo pode fazer.

O que acompanhar#

• Monitor de execuções (Integration → Runs): todas as execuções em uma lista: flow e versão, como foi disparado (horário / evento / manual), status (running, success, failed, retrying), duração e itens processados. Filtre por status para ver só as falhas.
• Detalhe da execução: clique em uma execução para vê-la nó a nó: captura de entrada e saída de cada passo e, no passo com falha, a mensagem de erro exata. Comece sempre aqui.
• Logs e mensagens mortas (Integration → Logs): itens que falham definitivamente vão para a fila de dead letters com o flow, o nó e o erro. Após corrigir a causa, repita (replay) o item para processá-lo de novo, ou descarte-o se não for mais necessário.
• Saúde da conexão: uma execução que falha no primeiro nó com erro de autenticação é problema da conexão, não do flow; o botão Testar da conexão o reproduz em segundos.

As cinco falhas abaixo cobrem quase tudo o que você verá. Para cada uma: como ela aparece, por que acontece e a correção, tudo pela interface.

1. Credenciais expiradas ou inválidas#

• Sintoma: execuções falham no primeiro nó com 401 / erro de autenticação; o teste da conexão falha igual. Costuma começar de repente após semanas funcionando.
• Causa: a outra plataforma expirou ou rotacionou a credencial: tokens têm vida útil (ex. Wish, 30 dias; alguns tokens OAuth de usuário, horas) e segredos mudam quando alguém os regenera.
• Correção: (1) obtenha uma credencial nova na plataforma (o diretório indica onde); (2) abra a conexão, cole o novo valor e salve; (3) teste a conexão até passar; (4) repita os dead letters gerados na falha.

2. Mapping ausente ou de tipo incorreto#

• Sintoma: execuções falham num nó intermediário com erros como “o campo X é obrigatório”, “SKU não mapeado” ou um valor rejeitado pelo tipo errado (texto onde vai número, data em formato errado). Pedidos novos com SKUs novos são o gatilho clássico.
• Causa: um campo de origem que o mapping espera veio vazio ou ausente naquele documento, os dois sistemas discordam sobre o tipo de um campo, ou um SKU do canal nunca foi vinculado a um produto OMS.
• Correção: (1) abra a execução com falha e veja qual nó e campo falharam; (2) SKUs não mapeados: vincule-os na lista pendente do Product Mapping; (3) campo ausente ou de tipo errado: abra o mapping do flow (ou da conexão), mapeie o campo correto ou adicione um padrão / conversão; (4) faça o dry run, publique se editou o flow e repita o dead letter.

3. A outra plataforma está limitando#

• Sintoma: execuções mostram “retrying” ou falham com 429 / “too many requests”. Rajadas pioram: após uma extração manual grande ou na hora cheia, quando muitos flows disparam juntos.
• Causa: cada plataforma limita as chamadas de API por minuto/hora de uma conta. O conector já tenta de novo com espera (isso é o “retrying”), mas uma rajada contínua pode esgotar a cota.
• Correção: (1) diante de um “retrying” ocasional, não faça nada: costuma se resolver sozinho; (2) se repetir, reduza a frequência de extração na conexão / no agendamento do flow; (3) escalone os agendamentos para vários flows não baterem na mesma plataforma no mesmo minuto; (4) evite extrações manuais repetidas enquanto há uma fila tentando de novo.

4. Falhas de webhook / retorno#

• Sintoma: dados que deveriam chegar por push nunca chegam (rastreio ou confirmações de fulfillment ausentes, avisos de pedidos novos parados) enquanto a extração manual continua funcionando. Os logs mostram erros de entrega de webhooks.
• Causa: a plataforma emissora não conseguiu entregar ao Docklify (problema temporário de rede), a assinatura foi perdida ao trocar as credenciais, ou a conexão foi desativada e reativada sem registrar o callback de novo.
• Correção: (1) veja em Integration → Logs os erros de webhook e seus horários; uma rajada curta que já parou não exige ação; (2) teste a conexão: um teste com sucesso revalida o registro do callback na maioria das plataformas; (3) se os pushes continuarem ausentes, desative e reative a conexão para forçar uma nova assinatura; (4) faça uma extração manual para recuperar o que faltou e acompanhe o próximo evento real.

5. Problemas de formato de dados#

• Sintoma: documentos avulsos falham enquanto outros da mesma conexão passam: um pedido rejeitado por endereço inválido, um telefone em formato incorreto, um CEP que não é interpretado ou um peso com a unidade dentro do número.
• Causa: o dado em si, como existe na plataforma ou no documento de origem, não cumpre as regras de formato do receptor. O flow e as credenciais estão bem; o documento não.
• Correção: (1) abra a execução com falha e leia qual documento e qual campo foram rejeitados: o erro os nomeia; (2) corrija o dado na origem onde puder (o endereço / telefone no pedido ou na plataforma); (3) se a mesma peculiaridade se repetir daquela plataforma, trate-a uma vez no mapping: padrão, corte ou conversão para aquele campo; (4) repita o dead letter do documento corrigido.