Hightouch's logs of sync executions ('runs') and Live Debugger make it easy to gain visibility into the requests and responses Hightouch makes to your destination during an execution ('run') of a sync.
To view the status of a run, simply click a run in any sync for a log of which rows were either added, changed, or removed:
In this sync, the status is 'healthy' meaning the sync behaved as expected with no error messages from the destination and no rejected rows.
'Added' means new records were returned from the query of the source and added to the sync.
'Removed' means records were no longer returned from the query of the source and removed from the sync.
'Changed' means some records are still returned from the query of the source but have updated values compared to the previous run.
In this run, the status is 'Failed' so it did not execute as intended. Several rows were 'rejected' meaning there was an error that prevented the row from being synced.
To view the error message for the entire run, click 'view run error'.
Hightouch will display error messages in the format they are sent to us by third-party APIs including standard HTTP status codes and any trace ids provided by the third-party:
To see the contents of a row error message, click 'view error' in the row table:
Hightouch will display error messages provided by the third-party API related to individual records.
If you have many runs of a sync to inspect, you can use the 'filter' option to only look at runs with 0 operations or 0 successful operations:
Use the search field to find a record with a primary key that matches the search value:
You can also export the data from all rows or just row errors as a CSV or JSON file:
Download and inspect the file to see details of rows that were added, changed, or deleted:
Or, download and inspect just the row errors:
Use your CSV editor's search feature to quickly locate records or specific error messages.
To take a closer look at the individual HTTP requests and responses that comprise a run (single sync execution), click any row to pull up the Live Debugger:
The Live Debugger view shows all the rows sent and responses received for the batch of rows that made up this particular request:
In this example, the POST request to update this batch failed because of a 400 error. In the response, Hightouch displays the error message from the third-party API telling us that there is an 'undefined' object in the request:
Hightouch displays the URL of the POST request used for diagnostic purposes. An 'undefined' sub-url means that the record ID number needed for this POST request failed to populate the URL and the data returned from the model will need to be inspected:
To expand a payload for closer inspection, click the 'expand' icon in the top right corner of the payload viewer:
Once expanded, you can scroll through the payload or click in the payload body and use command+F to bring up a search window:
Use the search window to find record IDs, email addresses, or any other payload data you need to inspect or trace.
To copy the payload, click the 'copy' button in the top right corner of the payload viewer; the payload will immediately be saved to your clipboard for pasting elsewhere:
For large, nested JSON payloads, it's helpful to paste the JSON into a viewer like CodeBeautify to view the payload's structure and values. Click 'tree viewer' to inspect the JSON as collapsible properties:
Use the run filter to narrow down your search to only the runs you need to inspect:
Use the run timestamps to isolate the runs you need to inspect based on your observation of when an error likely occurred. Run timestamps appear in your local timezone:
Use the Live Debugger to search payloads for missing records or to see how data was passed to your destination. Expand the payload viewer and use command+F to search for entities you need to inspect:
Since Hightouch returns error messages directly from third-party APIs as they occur, copy and paste the error message into your favorite search engine to find answers to commonly asked questions from other uses of that third-party API. Some destinations also have active developer communities where you can find explanations for many common error messages:
- Salesforce Developer Community
- HubSpot Developer Community
- NetSuite Support Community
- Stack Overflow (General Developer Community)
Hightouch will display HTTP status codes that are provided in your destination's HTTP response. These status codes are universal and can help you understand what may have gone wrong with your sync. If you see an HTTP status code in your Hightouch error message, it's coming from your destination and not from Hightouch.
HTTP status codes broken down into the following general categories:
- 1xx Informational Response. The request was received and understood. Request processing continues.
- 2xx Success. The request was successfully received, understood, and accepted.
- 3xx Redirection. Further action must be taken by the client to complete the request.
- 4xx Client Errors. An error may have been caused by the client. The request contains bad syntax or can't be fulfilled.
- 5xx Server Errors. The server has encountered an error and failed to fulfill the request.
The most common status codes we see in Hightouch syncs are:
200 success: This is good news and means your destination successfully received, understood, and accepted the request from Hightouch.
400 status: A 400 error usually means there is invalid data. Check that your data conforms to the destination's formatting expectations by checking the destination's API documentation.
401 status: A 401 error usually means there is a problem with the credentials you've used to set up your destination. Check that your credentials have permission to access the destination.
400 series errors are 'user errors', meaning the user needs to check that the credentials and data are correct and properly formatted.
500 series (500, 502, 504, etc) errors are 'server errors', meaning there is something wrong with the destination you are trying to sync to. Visit the status page of the destination to see if there are any reported outages (for example, Slack System Status or HubSpot Status). If a sync fails to send records because of a destination server error, Hightouch will have those records ready to send once the destination is back online.
Third-party APIs require the data you send to be of a specific data type. Unless otherwise specified, Hightouch takes the data from your source and leaves the data type unchanged to send to your destination. See Data Types and Casting for tips on resolving data type incompatibilities.