How to troubleshoot unhealthy connections

Updated:


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:

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

When a connection later stops working, your customer can go through the same flow again to re-authorize the existing connection. The connection keeps its ID. See Re-authorize an unhealthy connection below.

Understanding connection health

Connections in Unified.to have different health statuses based on recent credential and access checks:

  • Healthy: A recent API call or OAuth token refresh succeeded.
  • Unhealthy: The integration rejected the connection's credentials or access, and it has not successfully completed a call or token refresh since.
  • Unhealthy now: A recent API call or token refresh showed that the connection's credentials or access are no longer accepted, after previous successful activity.
  • New: The connection has been created but has not yet been used.

Unified marks a connection unhealthy when a integration no longer accepts its credentials or access. This may mean you need to review permission scopes and re-authorize the connection.

Other errors do not change connection health. This includes request-validation errors (400, 422), missing records (404), rate limits (429), and temporary integration errors (5xx). A connection can represent multiple objects and endpoints, so these errors may be specific to a request rather than an indication that the connection needs to be re-authorized.

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 (retention depends on your plan; see How long are logs retained).
  3. Look for recent credential or access errors, especially status codes 401-403.
  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

3. Re-authorize an unhealthy connection

Once you've fixed the cause (for example, restored your app's access or corrected scopes), ask your customer to re-authorize the existing connection rather than creating a new one. Re-authorizing keeps the same connection ID, so the connection IDs you've stored, your webhooks, and the connection's external_xref keep working.

  1. From your backend, create a re-authorization token with your API key:
    POST <https://api.unified.to/unified/connection/{CONNECTION_ID}/reauth>
    Authorization: bearer {YOUR_API_KEY}
    
    // Response
    { "reauth_token": "...", "expires_at": "..." }
    
  2. Send your customer to the usual authorization URL, adding connection_id and reauth_token:
    <https://api.unified.to/unified/integration/auth/>
    {WORKSPACE_ID}/{INTEGRATION e.g. hubspot}?redirect=true
    &connection_id={CONNECTION_ID}&reauth_token={REAUTH_TOKEN}
    &success_redirect={SUCCESS_URL}&failure_redirect={FAILURE_URL}
    
  3. Your customer signs in again. We test the new credentials the same way as when the connection was created.
  4. On success, the connection is updated in place and your customer is redirected to the success URL with the same id. You'll receive CONNECTION_UPDATED (and CONNECTION_HEALTHY if the connection was unhealthy) instead of CONNECTION_CREATED.

Re-authorizing without a scopes parameter asks for the same permissions the connection already has, and keeps its permissions and categories unchanged. To change them (for example, to add a scope that was missing), include scopes on the authorization URL with the full list you need.

The token is single-use and expires after 30 minutes, so create it right before you send your customer to the authorization URL. If the token is missing, expired, or already used, the failure URL receives error=authorization error: invalid or expired re-authorization link; create a new token and try again.

Learn more about re-authorizing connections

Troubleshooting by connection error codes

Authentication (401)

A 401 error is likely indicative that the connection's credentials are no longer valid and the connection needs to be re-authorized.

Possible causes:

  • Your app's access to the integration 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 integration's API.
  • Ensure that your customers are entering the correct values during the authorization flow.
  • After doing the above, re-authorize 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 integration expects and what Unified.to is requesting. This can happen when:

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 your developer account.

  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 integration's scopes (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-authorize the connection and include the full list of scopes you need on the authorization URL. Re-authorizing without scopes keeps the connection's current permissions, so a missing scope would stay missing. Re-create the webhook if needed, then try again.

A note on mappings:

A mapping of the Unified scopes to the 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 do not change connection health because 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 do not change connection health because 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 do not change connection health. 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 (also sent when a connection is re-authorized)
    • CONNECTION_DELETED
  4. Implement a handler for these events in your app to monitor connection health proactively.

Unified sends CONNECTION_UNHEALTHY when an integration rejects a connection's credentials or access. For API requests, the event description includes the integration's HTTP status when available, such as HTTP 401. If the issue continues, notifications are rate-limited to at most one per connection per hour. Unified sends CONNECTION_HEALTHY when a previously unhealthy connection successfully completes an API call or OAuth token refresh, or is re-authorized.

Treat these events as signals to review credentials and permission scopes, then re-authorize the connection if needed. For example, when you receive CONNECTION_UNHEALTHY, show the affected customer a "Reconnect" button in your app that creates a re-authorization token and sends them through the authorization URL. Your handler should be idempotent because an unhealthy connection can continue to generate periodic notifications until it is fixed.

Next steps

Remember, connection health is dynamic and can change after an authentication failure or a subsequent successful API call or OAuth token refresh. Not all errors indicate a broken connection.

Share
All guidesUnified Connection modelAccounting Account Type Hierarchy in UnifiedAdvertising Report Metrics by IntegrationAmazon S3: Required IAM PermissionsATS to Vector DB: How to Power Talent Intelligence with Real-Time DataBuilding AI applications with Unified and LangbaseConcur & Concur (Company) — Connection GuideConfigure Greenhouse Native Candidate WebhooksConfigure Salesforce Meetings and Notes for UnifiedConnect Amazon Seller Central to Unified.toConnecting BambooHR via OAuth 2Connecting Google Workspace Integrations with a Service AccountCorrect WelcomeKit Scopes for Jungle IntegrationCreating Ads using the Unified Ads APICreating Walmart Items via UnifiedEnd-Users, Integrations, and ConnectionsEnriching Unified Objects with Custom MetadataEnterprise-managed authorization (EMA) with a static keyEnterprise-managed authorization (EMA) with a workspace secretEnterprise-managed authorization (EMA) with Microsoft Entra IDExtended observability — pushing API logs to ClickHouseExtended observability — pushing API logs to Grafana / LokiExtended Observability - Pushing API Logs to your Datadog InstanceFacebook Messenger Webhook SetupFireflies Integration GuideGetting started with WorkableHandling Delegated vs. Application Scopes in Microsoft IntegrationsHiBob & Unified: connection and time off guideHow long are logs retainedHow to access employees and usersHow to add API support for the Create Activity in CrelateHow to Associate a Connection ID with Your End-UserHow to build a Candidate Assessment product withHow to build a candidate sourcing or job board app with Unified.toHow to build a Discord support bot with Unified.to and LangbaseHow to Build a Fintech Application with Unified's Payments APIHow to Build an E-Commerce Product Integration with UnifiedHow to build an invoicing system with Unified.toHow to build Enterprise Search using RAGHow to configure Bullhorn Redirect URI for creating a connectionHow to configure webhooks in HubSpotHow to configure webhooks in Thrive LearningHow to configure webhooks in Toast for UnifiedHow to Connect Anthropic to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Cohere to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Google Gemini to Real-Time SaaS Data with Unified.to MCP ServerHow to connect HiBob (Bob) to Unified with OAuth 2.0How to Connect LLMs to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect OpenAI to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Zoom and Zoom PhoneHow to create a Connection In Microsoft TeamsHow to create a token-based connection in HighlevelHow to Create a Unified.to Connection to HighLevelHow to Create a Xero Connection in Unified.toHow to create and configure webhooksHow to create Connection with HubspotHow to customize portal URLs for Stripe and GoCardlessHow to filter webhook eventsHow-to Get a Private Support Channel for Your Unified IntegrationHow to get help fromHow to get your 8x8 Connect API Key, Account ID and SMS Subaccount ID (optional): Step-by-step guideHow to get your ADP Workforce Now Oauth2 client ID, Oauth2 client secret, Oauth2 PEM certificate and Oauth2 private key: Step-by-step guideHow to get your Amazon S3 AWS Region, AWS S3 Key, AWS S3 Secret and AWS S3 Bucket(s) (optional, comma-separated): Step-by-step guideHow to get your Ashby API Key: Step-by-step guideHow to get your Brex API token: Step-by-step guideHow to get your Bullhorn OAuth2 Client ID, OAuth2 Client Secret, API Username and API Password: Step-by-step guideHow to get your Ceridian Dayforce Username, Password and Client Namespace: Step-by-step guideHow to get your Crelate API key: Step-by-step guideHow to get your Dashlane API Key: Step-by-step guideHow to get your Deel Access Token: Step-by-step guideHow to get your Dialpad API Key: Step-by-step guideHow to get your Discord OAuth 2 credentials and bot tokenHow to get your ELMO client ID and client secret: Step-by-step guideHow to get your Gainsight Client ID, Client Secret and Gainsight API Domain: Step-by-step guideHow to get your Greenhouse API Key and Job board token: Step-by-step guideHow to get your Helpscout API Key: Step-by-step guideHow to get your HiBob Service User ID and Service User Token: Step-by-step guideHow to get your HighLevel API Key and Location ID: Step-by-step guideHow to get your HubSpot developer key and OAuth 2 credentials (Legacy Apps)How to get your Humaans API Key: Step-by-step guideHow to get your iCIMS API Username, API Password and Customer ID: Step-by-step guideHow to get your JobDiva Client ID, Username/email and Password: Step-by-step guideHow to get your Jobvite API Key, API Key Secret and Email: Step-by-step guideHow to get your Lever API Key: Step-by-step guideHow to get your Loxo Agency slug, API Key and Agency ID: Step-by-step guideHow to get your Microsoft Active Directory / Entra ID Client ID, Client Secret and Tenant ID: Step-by-step guideHow to get your Microsoft Azure AD OAuth 2 credentialsHow to get your OAuth 2 credentials for GmailHow to get your OAuth 2 credentials for Microsoft Dynamics 365How to get your OAuth 2 credentials in PipeDriveHow to get your OpenAI API Key: Step-by-step guideHow to get your Paycom SID/Username and Token/Password: Step-by-step guideHow to get your PCRecruiter Username, Password, Database ID, App Key and App ID: Step-by-step guideHow to get your SAP SuccessFactors (OpenID Connect) Username, Password, Client ID, Client Secret, Dependency Name, IAS Host and API URL: Step-by-step guideHow to get your SAP SuccessFactors Username, Company ID, Password and API URL: Step-by-step guideHow to get your Shopify Admin API access token and Store ID: Step-by-step guideHow to get your Wayfair Client ID, Client Secret and Vendor Encrypted Key: Step-by-step guideHow to get your Workable API Token and Subdomain: Step-by-step guideHow to get your yotpo APP Key / Store ID and Secret Key: Step-by-step guideHow to Handle Attachments in Invoice, Bill and Credit MemoHow to Manage Google Ad Manager Orders, Line Items and Creatives with theHow to migrate or import your integrations into Unified.toHow to obtain your GitHub OAuth2 credentialsHow to Power Claude with Live Customer Data Using Unified MCPHow to receive assessment orders from an ATS with Unified.toHow to register a Google developer app and get OAuth 2 credentialsHow to Register a HiBob Developer App and Get OAUTH2 CredentialsHow to register a Salesforce developer app and get OAuth 2 credentialsHow to register a Slack developer account and get OAuth 2 credentialsHow to Register a Workday Developer App and Get OAUTH2 CredentialsHow to Register a Workday Developer App and Get OAUTH2/ SOAP CredentialsHow to Register a ZendeskSell Developer App and Get OAUTH2 CredentialsHow to Register a Zoho Developer App and Get OAUTH2 CredentialsHow to Register an ADP Developer App and Get OAUTH2 CredentialsHow to Register an Atlassian Developer App and Get OAUTH2 CredentialsHow to Register your Facebook OAuth2 ApplicationHow to Register your Google Ads OAuth2 ApplicationHow to Register your MetaAds OAuth2 applicationHow To Request & Write Raw Integration DataHow to Retrieve Microsoft Dynamics 365 Business Central CredentialsHow to set up a custom API URL with a CNAMEHow to Set Up a Google Meet Meeting Bot with UnifiedHow to set up a HiBob marketplace installHow to Set Up a Microsoft Teams Bot with UnifiedHow to Set Up a Microsoft Teams Meeting Bot with UnifiedHow to Set Up a Webex Meeting Bot with UnifiedHow to Set Up a Zoom Meeting Bot with UnifiedHow to set up and configure NotionHow to set up Google Business Profile API access and get OAuth 2 credentialsHow to Set Up LinkedIn Webhooks with UnifiedHow to set up native webhooks for QuickBooks Online with UnifiedHow to set up Slack webhooks using event subscriptionsHow to set up Telegram (bot) with Unified.toHow to set up your scopes in HubSpotHow to setup a Freshbooks developer appHow to setup a TikTok Shop applicationHow to Setup AWS Assume Role for AWS Secret ManagerHow to setup Oracle JD EdwardsHow to Setup Quickbooks DesktopHow to setup Sage 100 with Unified.toHow to test webhooks in the Synthetic Data (Sandbox) environmentHow to troubleshoot unhealthy webhooksHow to Use Decision Models with the Unified GenAI APIHow to use SCIM with the Unified APIHow to use the Passthrough APIHow to Use Unified.to's Generative AI API with OpenAI and ClaudeHow to use User Provisioning and Verification with UnifiedHow virtual webhook retry and recovery worksIntegration set-up guide for LeverManaging custom validation rules in SalesforceNetSuite Authentication Setup for UnifiedNotice of Deprecation of Fields and Objects (Nov 2025)Oracle HCM / Taleo OAuth Credentials GuideRetrieval-Augmented Generation (RAG)SalesForce (External Client Apps) on Multiple OrganizationsSAML Single-Sign-OnScaling MCP Tools with Anthropic's (& OpenAI's) Defer LoadingScaling MCP Tools with Anthropic's Programmatic Tool CallingSet Environments for your Unified.to WorkspaceSetting up a Slack Bot Connection with Unified.toSetting up OAuth 2 Credentials for Greenhouse's APIsTrello Connection Guide in UnifiedUnderstanding OAuth2 Authorization flowsUnderstanding Response Time Headers in the Unified APIUnified Assessment API: Embed Assessments Inside ATS PlatformsUnified's MCP ServerUnified MCP Server with LangChain and LangGraphUnlock real-time data with virtual webhooksUse Unified to sign in your users into your applicationVincere OAuth Setup Guide for UnifiedWhy you can't use Unified's OAuth2 credentials to authorize your end users on ProductionWorkable: Creating candidates and attaching them to jobsWorkday vs Workday Legacy — Why Unified.to Supports BothWorking with hierarchical tree data in Storage, Messaging, and KMS APIs
Are we missing anything? Let us know
Was this page helpful?