Use este artigo para ler e interpretar logs do conector de dados, identificar a causa dos erros do conector e tomar as medidas corretas para resolvê-los. Este artigo é para colegas que configuraram pelo menos um conector de dados e precisam diagnosticar por que ele está falhando.
Como acessar logs do conector de dados
Os logs do conector de dados mostram o histórico de cada solicitação feita pelo conector. Para abrir os logs de um conector, vá para Configurações > Integrações > Data Connectors, selecione um conector e abra a aba Logs.
Como encontrar logs para uma conversa específica
Para ver quais data connectors foram executados durante uma conversa específica (e se algum falhou), abra a conversa no Inbox e ative a visualização do histórico de eventos na linha do tempo da conversa. Execuções de data connectors que falharam aparecem destacadas em vermelho.
Como ler logs
A área de logs tem três componentes principais. Selecione qualquer solicitação na lista para abrir o painel de detalhes:
Filtro: Você pode filtrar os logs por diferentes valores e intervalos de tempo.
Lista de solicitações: Cada entrada mostra a data e hora, o que acionou o conector e se a solicitação foi bem-sucedida ou falhou.
Detalhes da solicitação: Mostra uma divisão de cada etapa pela qual a solicitação passou e em qual etapa ela falhou.
Filtrar
Use o seletor de intervalo de datas para filtrar logs por um período específico.
Você também pode filtrar por qualquer um dos seguintes valores:
ID de execução: Um identificador único para cada solicitação do conector. Nossa equipe de suporte pode pedir isso ao diagnosticar problemas.
ID da conversa
Status (Sucesso/Falha)
Tipo de falha:
Erro de configuração da solicitação: O conector está configurado incorretamente — por exemplo, a URL ou um campo obrigatório está faltando ou errado — então o Fin não conseguiu nem tentar a chamada.
Erro Faraday: Um erro de conectividade em nível de rede — o Fin não conseguiu alcançar o serviço externo. Isso geralmente é causado por timeout, falha de DNS ou servidor inacessível. Verifique se o serviço externo está online e se a URL do conector está correta.
Erro de API de terceiros (application programming interface): O Fin alcançou o serviço externo com sucesso, mas o serviço retornou um erro na resposta — por exemplo, a solicitação foi rejeitada ou o serviço estava temporariamente indisponível. Contate o provedor do serviço externo e compartilhe a resposta de erro para investigação.
Erro de mapeamento da resposta: O serviço externo respondeu com sucesso, mas o Fin não conseguiu ler ou extrair os dados da resposta da forma esperada.
Erro de atualização do token: O token OAuth (Open Authorization) usado para autenticar com o serviço externo expirou, e a tentativa automática de renovação falhou. Use o botão Reauthenticate nas configurações do conector para restaurar o acesso.
Erro de validação da solicitação: Os dados que o Fin estava prestes a enviar foram verificados e considerados inválidos ou incompletos antes mesmo da solicitação ser feita.
Erro de transformação do bloco de código: Um trecho de código personalizado que o conector usa para reformular dados antes de enviar ou após receber travou ou produziu um resultado inesperado.
Executado em:
Fin: O conector foi acionado pelo Fin AI enquanto ele estava lidando com uma conversa com o cliente.
Procedure: O conector foi acionado por uma Procedure — uma tarefa estruturada ou workflow que o Fin segue passo a passo.
Inbox: O conector foi acionado manualmente por um colega diretamente de uma conversa no inbox.
Inbox Automation Rule: O conector foi acionado automaticamente por uma regra configurada para executar ações quando certas condições são atendidas no inbox.
Custom Bot: O conector foi acionado por um fluxo de bot criado no construtor de Workflows para automatizar conversas.
Resolution Bot: O conector foi acionado pelo antigo Resolution Bot enquanto tentava responder automaticamente a uma pergunta do cliente.
Macros (Saved Reply): O conector foi acionado quando um colega usou uma resposta salva (macro) em uma conversa.
Detalhes da solicitação
Selecionar uma solicitação da lista abre seu painel de detalhes. As quatro seções a seguir cobrem cada etapa da execução do conector de dados:
Execução
Solicitação
Resposta
Processamento da resposta
Cada uma das quatro seções representa uma fase distinta da solicitação do conector de dados:
Execução cobre todo o ciclo de vida da solicitação do início ao fim. Mostra o que acionou o conector de dados — por exemplo, Fin AI Agent, uma Procedure ou um colega no Inbox.
Solicitação é o que o Fin envia para o sistema externo. Se houver um erro aqui, a solicitação nunca foi enviada. Isso geralmente é causado por um problema com a URL, o payload da solicitação ou a configuração do conector. Se a causa não estiver clara, contate o suporte com os detalhes do log de execução.
Resposta é o que o sistema externo retorna para o Fin. Um código de status 200 indica sucesso. Códigos de status na faixa 5XX (como 500 ou 502) indicam erro no servidor do sistema externo — compartilhe a resposta de erro com o provedor do serviço externo para investigação. Códigos de status na faixa 4XX indicam erro do lado do cliente: 404 significa que o recurso solicitado não foi encontrado, enquanto 401 e 403 indicam problemas de autenticação ou autorização. Em geral, erros 4XX significam que a solicitação enviou dados inválidos, incompletos ou não autorizados.
Processamento da resposta é onde o Fin aplica o mapeamento de resposta configurado na configuração do conector de dados. Se esta etapa falhar, geralmente significa que a resposta da API tem uma estrutura diferente do esperado pelo conector. Revise o mapeamento de resposta nas configurações do conector e contate o suporte com os detalhes do log se o problema persistir.
Por que meu conector de dados tem sucesso, mas o Fin diz que não encontrou nada?
Um conector de dados pode executar com sucesso — retornando um código de status 200 — mas ainda assim fazer o Fin AI Agent dizer que não encontrou nada. Isso geralmente acontece quando o payload da resposta da API é muito grande ou não estruturado para o Fin extrair os dados relevantes. Para resolver isso, otimize a resposta da API para retornar apenas os campos específicos que o Fin precisa, em vez de enviar um objeto de dados completo. Se o problema persistir após reduzir o tamanho da resposta, contate o suporte.
Dica: Para problemas específicos de data connectors executando dentro de uma Procedure, veja Solução de problemas em Fin Procedures e Data connectors.