Use this article to read and interpret data connector logs, identify the cause of connector errors, and take the right steps to resolve them. This article is for teammates who have set up at least one data connector and need to diagnose why it's failing.
How to access data connector logs
Data connector logs show a history of every request the connector has made. To open the logs for a connector, go to Settings > Integrations > Data Connectors, select a connector, then open the Logs tab.
How to find logs for a specific conversation
To see which data connectors ran during a specific conversation (and whether any failed) open the conversation in the Inbox and enable the event history view from the conversation timeline. Failed data connector executions appear highlighted in red.
How to read logs
The logs area has three main components. Select any request in the list to open its details panel:
Filter: You can filter the logs by different values and time ranges.
List of requests: Each entry shows the date and time, what triggered the connector, and whether the request succeeded or failed.
Request details: Shows a breakdown of each stage the request went through and which stage it failed at.
Filter
Use the date range picker to filter logs by a specific time period.
You can also filter by any of the following values:
Execution ID: A unique identifier for each connector request. Our support team may ask for this when diagnosing issues.
Conversation ID
Status (Success/Failure)
Failure type:
Request configuration error: The connector is set up incorrectly — for example, the URL or a required field is missing or wrong — so Fin couldn't even attempt the call.
Faraday error: A network-level connectivity error — Fin couldn't reach the external service at all. This is typically caused by a timeout, DNS failure, or the server being unreachable. Check whether the external service is online and that the connector URL is correct.
3rd party API (application programming interface) error: Fin reached the external service successfully, but the service returned an error in response — for example, the request was rejected or the service was temporarily unavailable. Contact the external service provider and share the error response for investigation.
Response mapping error: The external service replied successfully, but Fin couldn't read or extract the data from the response in the expected way.
Token refresh error: The OAuth (Open Authorization) token used to authenticate with the external service expired, and the automatic renewal attempt failed. Use the Reauthenticate button in the connector settings to restore access.
Request validation error: The data Fin was about to send was checked and found to be invalid or incomplete before the request was even made.
Code block transformation error: A custom code snippet the connector uses to reformat data before sending or after receiving it crashed or produced an unexpected result.
Executed in:
Fin: The connector was triggered by Fin AI while it was handling a customer conversation.
Procedure: The connector was triggered by a Procedure — a structured task or workflow that Fin follows step-by-step.
Inbox: The connector was triggered manually by a teammate directly from a conversation in the inbox.
Inbox Automation Rule: The connector was triggered automatically by a rule set up to run actions when certain conditions are met in the inbox.
Custom Bot: The connector was triggered by a bot flow built in the Workflows builder to automate conversations.
Resolution Bot: The connector was triggered by the older Resolution Bot while it was trying to automatically answer a customer's question.
Macros (Saved Reply): The connector was triggered when a teammate used a saved reply (macro) in a conversation.
Request details
Selecting a request from the list opens its details panel. The following four sections cover each stage of the data connector execution:
Execution
Request
Response
Response processing
Each of the four sections represents a distinct phase of the data connector request:
Execution covers the full lifecycle of the request from start to finish. It shows what triggered the data connector — for example, Fin AI Agent, a Procedure, or a teammate in the Inbox.
Request is what Fin sends to the external system. If there's an error here, the request was never sent. This is usually caused by an issue with the URL, the request payload, or the connector configuration. If the cause isn't clear, contact support with the execution log details.
Response is what the external system returns to Fin. A status code of 200 indicates success. Status codes in the 5XX range (such as 500 or 502) indicate a server-side error on the external system — share the error response with the external service provider for investigation. Status codes in the 4XX range indicate a client-side error: 404 means the requested resource wasn't found, while 401 and 403 indicate authentication or authorization issues. In general, 4XX errors mean the request sent invalid, incomplete, or unauthorized data.
Response processing is where Fin applies the response mapping configured in the data connector setup. If this step fails, it usually means the API response has a different structure than the connector expected. Review the response mapping in the connector settings, and contact support with the log details if the issue persists.
Why does my data connector succeed but Fin says it can't find anything?
A data connector can execute successfully — returning a 200 status code — but still cause Fin AI Agent to say it couldn't find anything. This usually happens when the API response payload is too large or unstructured for Fin to extract the relevant data from. To resolve this, optimize the API response to return only the specific fields Fin needs, rather than sending a full data object. If the issue persists after reducing the response size, contact support.
Tip: For issues specific to data connectors running inside a Procedure, see Troubleshooting Fin Procedures and Data connectors.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts