Search documentation...

K

Debugger

Overview

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.

View the status of a run

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:

View the status of a sync

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.

View rejected rows

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.

View error messages

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:

View error message

To see the contents of a row error message, click 'view error' in the row table:

Not found error message

Hightouch will display error messages provided by the third-party API related to individual records.

Filter runs

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:

Filtering runs

Search rows

Use the search field to find a record with a primary key that matches the search value:

Search rows

Export rows and row errors

You can also export the data from all rows or just row errors as a CSV or JSON file:

Export rows

Download and inspect the file to see details of rows that were added, changed, or deleted:

Inspect CSV

Or, download and inspect just the row errors:

Inspect CSV row errors

Use your CSV editor's search feature to quickly locate records or specific error messages.

Using the live debugger

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:

Launch 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:

Live Debug Rows

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:

Debugging POST error

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:

Undefined URL error

Inspecting payloads

To expand a payload for closer inspection, click the 'expand' icon in the top right corner of the payload viewer:

Expand the payload

Once expanded, you can scroll through the payload or click in the payload body and use command+F to bring up a search window:

Scroll and search payload

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:

Copying the payload

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:

Viewing JSON in Code Beautify

Hightouch debugging tips

Run filters

Use the run filter to narrow down your search to only the runs you need to inspect:

Use run filters

Run timestamps

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 run timestamps

Search the live debugger

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:

Search the Live Debugger

Search error messages

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:

Understand HTTP status codes

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.

Search the Live Debugger

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.

Data types and casting

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.

    Need help?

    Our team is relentlessly focused on your success. We're ready to jump on a call to help unblock you.

    • Connection issues with your data warehouse?
    • Confusing API responses from destination systems?
    • Unsupported destination objects or modes?
    • Help with complex SQL queries?

    Feature Requests?

    If you see something that's missing from our app, let us know and we'll work with you to build it!

    We want to hear your suggestions for new sources, destinations, and other features that would help you activate your data.

On this page

OverviewView the status of a runView error messagesFilter runsSearch rowsExport rows and row errorsUsing the live debuggerInspecting payloadsHightouch debugging tipsRun filtersRun timestampsSearch the live debuggerSearch error messagesUnderstand HTTP status codesData types and casting

Was this page helpful?