How to troubleshoot unhealthy connections

September 25, 2024

Connections allow your application to securely access data from third-party API platforms. They serve as links between your Unified.to workspace, your customers' data, and your app.

Whether you're encountering issues during connection creation or debugging an existing connection that has become unhealthy, this guide will help you identify and resolve the problem. We'll walk you through how to interpret error messages, check connection status, and implement solutions to get your integrations running smoothly again.

Before you begin

This guide assumes you have a basic understanding of:

• Scopes

Connection lifecycle

Understanding the connection lifecycle can help in troubleshooting:

1. Your customer selects an integration from your app to authorize.
2. Your customer is directed to the authorization page for that integration.
3. Unified.to determines what to display on the page (e.g. OAuth vs API token)
4. Your customer grants access to their account.
5. Unified.to's server creates a connection in memory and attempts to test it immediately.
   1. If tests pass, the connection is created in our database and your customer is redirected to the success URL you specified (defaults to the page they were on when they started the auth flow).
   2. If tests fail, the customer is redirected to the failure URL you specified with error details in the query parameters. See the below section: Handle errors during connection creation

Understanding connection health

Connections in Unified.to have different health statuses based on their recent activity:

• Healthy: The connection is working as expected.
• Unhealthy: The connection has failed and hasn't had a successful call since.
• Unhealthy now: The connection has had a recent failure after previous successes.
• New: The connection has been created but hasn't been used yet.

It's important to note that a connection can represent multiple objects and endpoints, each with its own potential for errors. Not all errors are terminal or indicative of a broken connection.

Handle errors during connection creation

When a connection fails to be created, we redirect users to the failure URL (this defaults to the page where the auth flow was initiated). The redirect URL includes two query parameters:

• error: An error message
• log_id: The ID of the API call log entry for this failure

To properly handle these errors in your application:

1. Review the API call log:
   • Go to API Call Logs in your Unified.to dashboard
   • Look up the log entry using the log_id from the URL
   • Examine the error message and status code to understand what went wrong
2. Implement error handling in your app
   1. For example, you may want to display a friendly message to your users, log the error in your monitoring tool, or invite them to contact support

Review the section below, "Troubleshooting by connection error codes", for a detailed walkthrough of the possible error codes and how to handle them.

Handle errors after a connection is created

When a connection is created successfully but becomes unhealthy later on, the first place to look for debugging information is in the API call logs.

1. Check the connection status

1. Navigate to the Connections page
2. Look for connections marked as Unhealthy or Unhealthy now.

2. Review API call logs

1. Go to API Call Logs.
2. Filter the logs by the connection ID of the unhealthy connection (note: we only store logs from the past 60 days).
3. Look for recent error logs (status codes 400 and above).
4. Click on an error log to view details about the failed API call.

You can also use the Unified API to retrieve a list of your connections and API call logs. Pass the connection_id to the API calls endpoint to filter by that connection.

API reference: List all connections, List all API calls

Troubleshooting by connection error codes

Authentication (401)

A 401 error is likely indicative that the connection is broken and requires recreation.

Possible causes:

• Your app's access to the provider has been revoked.
• In non-OAuth flows that ask your customers to input an API key or other information, they may have input the wrong values.

Solutions:

• Double check that your app still has access to the API provider.
• Ensure that your customers are entering the correctly values during the authorization flow.
• After doing the above, recreate the connection to refresh the authentication
• If the issue persists for specific endpoints, contact Unified.to support for assistance.

Permissions (403)

A 403 error is likely indicative that one or more data objects is not working as expected, usually due to misconfigured scopes.

Possible causes:

• Mismatch between the scopes that the provider expects and what Unified.to is requesting. This can happen when:
  • Scopes have been changed or disabled on the provider's end i.e. in your developer account, or
  • The proper scopes are not being requested when setting up the Authorization embedded component or when generating an authorization URL.

Solutions:

1. Double check your scope settings in your developer account
   1. Log into your developer account for the API you're trying to access.
   2. Navigate to the settings page where your app's authorization options are found.
   3. Ensure that all necessary scopes are enabled (see note below on different integrations and how they handle scopes)
   4. Make a note of the scopes that are enabled.
2. Double check your scope settings on Unified.to

If you are using our embedded components to create connections, you'll need to ensure that the scopes on Unified.to match the ones you enabled in the API provider.

1. Navigate to the Embedded components page
2. Click Permission Scopes
3. Select the scopes that match the scopes you enabled in the developer account (see note below on mappings)
4. (Optional, only if you are using webhooks) Select the webhook scope
5. If the issue still persists, contact Unified.to support for assistance

If you are generating an auth URL to redirect your customers to our auth flow, include scopes as a query parameter and list all the Unified scopes you need. Behind the scenes, Unified.to will map the Unified scopes you pass to the scopes on the API provider's end (see note below on mappings). For example:

https://api.unified.to/unified/integration/auth/
{WORKSPACE_ID}/{INTEGRATION e.g. hubspot}?redirect=true
&scopes=webhook,{YOUR_SCOPES e.g. crm_deal_read, crm_event_read}

API reference: Create an authorization URL

After addressing these issues, re-create the connection and/or webhook and then try again.

A note on mappings:

A mapping of the Unified scopes to the API provider (i.e. integration's) scopes can be found on the integration details page under the OAuth 2 Credentials tab e.g. here are the mappings for HubSpot scopes.

A note on integration-specific scopes:

Different integrations may handle scopes in different ways - sometimes you can request a subset of the scopes enabled in the developer account, other times you must request all the scopes that have been enabled, and in the case of Hubspot, scopes are divided into Required and Optional scopes. For these cases, we have written how-to guides on generating OAuth credentials and configuring scopes. Please consult the Unified.to docs for more information about these integrations.

Not found (404)

Note: For Enrichment category integrations, 404 errors are treated as successful responses. They indicate that no data was found for the provided input, not that the connection is broken.

Solution:

• Verify that the input data (e.g., email, company name) is correct.

Rate limiting (429)

429 errors are treated as successful responses by Unified.to as they indicate the connection is active but temporarily limited.

Possible cause:

• Exceeding the API rate limits of the third-party service

Solutions:

• (Recommended) Use webhooks to read data and Unified.to will take care of rate limiting for you.
• Implement request throttling in your application.
• Contact the third-party service to request increased rate limits.

Server errors (500 series e.g. 502, 503, etc)

500 series errors are often treated as successful responses by Unified.to as they usually indicate temporary issues with the third-party service. In cases where the issue is on our end, however, we will attempt to make that clear in the error message.

Possible causes:

• Temporary issues with the third-party service
• Bugs

Solutions:

• Check the status page of the third-party service for any ongoing issues.
• Retry the request after a short delay.
• If the issue still persists or if you've discovered a bug, contact Unified.to support for assistance. Thank you!

Not implemented (501)

501 errors are treated as successful responses by Unified.to. They indicate that a specific functionality is not implemented for the integration, not that the connection is broken.

Suggestion actions:

• Check the Unified.to documentation for the specific integration to understand its supported features.
• If you believe the functionality should be supported, contact Unified.to support and we'd be happy to look into it.

Monitor and receive updates about your connections

To stay informed about changes to your connections:

1. Navigate to Settings > Workspace.
2. Under Notifications webhook URL, enter the URL where you want to receive notifications (this should be an endpoint on your server that can receive POST requests).
3. Under Notifications webhook events, select events related to connections:
   • CONNECTION_HEALTHY
   • CONNECTION_UNHEALTHY
   • CONNECTION_CREATED
   • CONNECTION_UPDATED
   • CONNECTION_DELETED
4. Implement a handler for these events in your app to monitor connection health proactively.

Next steps

• Join our Discord community for support and updates.
• If issues persist, contact our support team for further assistance.

Remember, connection health is dynamic and can change with each API call. Not all errors indicate a broken connection, and some error types are treated as successful responses in certain contexts.