Error Handling

Suggest Edits

When triggering a transfer, it is important to handle errors returned by the Endgrate API.

There are two ways to get transfer error information. You can either specify a webhook when initiating your push or pull, or hit an Endgrate endpoint to query for the data.

We recommend using the webhook method. To do so, simply specify the error_webhook when initiating your push (POST api/push/transfer) or pull (POST api/pull/transfer). Endgrate will automatically POST data to your webhook if there are any transfer errors. The format of the POST request is detailed in the API webhook reference and below:

{
  "success": true,
  "pk": "65c9c40982664224123cebd5",
  "transfer_id": "6566e87b7cf20dca9cef0c0d",
  "session_id": "6566e85e7cf20dca9cef0c0a",
  "timestamp": "2023-08-28T02:04:08.917Z",
  "error_resolve_text": "There is a mapping error or invalid data point in one or more fields. The field 'testdate' looks like a date and is not a valid long number. It must be a valid long number.",
  "error_type": "mapping",
  "resolved": true,
  "endgrate": {
    "provider_info": {
      "name": "hubspot",
      "display_name": "HubSpot",
      "url": "https://www.hubspot.com/",
      "image": "https://endgrate.nyc3.cdn.digitaloceanspaces.com/integration/hubspot.png",
      "auth_type": "oauth",
      "endgrate_provider_type": "CRM"
    },
    "integration_info": {
      "name": "get-contacts",
      "display_name": "Get Contacts",
      "method": "IMPORT",
      "endgrate_type": "crm-contact",
      "supports_associations": true
    }
  }
}

Pay special attention to the "error_type" attribute.

  • The internal error type indicates a problem with the Endgrate server.
  • The integration error type indicates a problem with the Endgrate integration implementation.
  • The mapping errors indicates a problem with the data mapping.
  • The upstream error type indicates a problem that arises from the integration itself. Examples of upstream errors include if there is a missing required field for an integration, or if the integration itself returns an error.
  • The authentication error type is related to user authentication processes, including login issues, problems with access tokens, or expired authentication. To handle this error, have the user reauthenticate their session by redirecting them to the GET /session/reauthenticate page.

The main two error types that must be handled are upstream errors and authentication errors. The other errors are relatively rare.

For upstream errors, return the error_resolve_text to your end user.

For authentication errors, redirect your end user to the reauthenticate page as specified above.

You can also query errors through the paginated GET api/errors endpoint and filter by a session ID or a transfer ID.

Updated 2 months ago