Connection errors are among the most common issues encountered when building automations.
Overview
Connection errors are among the most common issues encountered when building automations. This guide covers the four main error categories, how to read the connection error panel in UnifyApps, and general sanity checks to run before contacting support.
API Timeout Issues
Timeout errors occur when a connection attempt or API call does not receive a response within the allowed time window. These are almost always network or infrastructure issues rather than credential problems.
IP Whitelisting
Many enterprise APIs restrict inbound requests to known IP addresses. If UnifyApps' outbound IP addresses are not whitelisted on the target service's firewall or API gateway, all requests will time out.
Resolution: Obtain the current list of UnifyApps outbound IP addresses from the platform settings or by contacting support, then add them to the external service's IP allowlist.
SSL Certificate Issues
Connections to services with invalid, expired, or self-signed SSL certificates may fail or time out depending on the connector's certificate validation settings.
Resolution: Verify the target service's SSL certificate is valid and trusted. For internal or dev environments using self-signed certificates, use the Custom HTTP Endpoint node with "Verify SSL Certificates" set to False — do not disable verification for production connections.
SSH Tunnel
Connections routed through an SSH tunnel may time out if the tunnel configuration is incorrect, the tunnel host is unreachable, or the tunnel has been closed.
Resolution: Verify the SSH host, port, username, and key configuration. Confirm the tunnel endpoint is accessible from UnifyApps' network. Check that the tunnel host allows connections from UnifyApps' IP addresses.
Incorrect Input Details
Authentication failures and "invalid credentials" errors are the most common category of connection error and almost always indicate a configuration mistake rather than a platform issue.
Connection Troubleshooting details
Authentication Credentials
Verify API keys, tokens, and secrets are copied completely with no leading or trailing whitespace
Check that OAuth tokens have not expired — re-authenticate if needed
Confirm the credentials have the necessary permissions/scopes for the actions being performed
For Basic Auth, verify the username and password are for the correct environment (staging vs. production)
Configuration Parameters
Verify the Base URL includes the correct scheme (https://) and does not have a trailing slash if the connector does not expect one
Check region or instance-specific parameters (e.g., AWS region, Salesforce instance URL, database host)
Confirm port numbers for database and SSH connections match the service configuration
Mandatory Fields Not Filled
Some connectors require specific fields that may not be immediately obvious. Leaving required fields blank causes the connection test to fail with a validation error rather than an authentication or network error.
Review all fields in the connection form, including optional-looking sections that may contain required sub-fields
Check service-specific requirements: some APIs require a workspace ID, organization slug, or account identifier in addition to the API key
For database connections, ensure the database name, schema, and SSL mode fields are all populated
OAuth Redirection Issues
OAuth-based connections require a browser redirect flow. Problems in this flow prevent the connection from being established even with correct credentials.
Ensure the UnifyApps OAuth redirect URI is registered in the external application's OAuth settings
Check that pop-up blockers are not preventing the OAuth authorization window from opening
Verify the OAuth application's redirect URIs list matches the URI UnifyApps presents during the authorization flow
If re-authenticating, revoke the existing OAuth token in the external application before starting the flow again
Reading the Error Panel
When a connection fails, UnifyApps displays a red alert banner in the connection configuration panel.
Click the Show Details button on the alert banner to expand the error panel.
The expanded panel shows the HTTP status code, error message from the external service, and any additional context UnifyApps captured during the connection attempt.
Use the HTTP status code to narrow down the category: 401/403 indicates an authentication or permission issue; 404 indicates an incorrect URL or endpoint; 408/504 indicates a timeout; 5xx indicates a problem on the external service's side.
Expanded error panel showing HTTP status code and error message details
General Sanity Checks
Test the credentials directly using a tool like curl or Postman before configuring them in UnifyApps
Confirm the external service is operational — check the service's status page if available
Try creating a new connection rather than editing an existing one, in case cached state is causing issues
Check that the connected account has not been deactivated, locked, or had its permissions changed
For time-sensitive tokens, verify the system clock on the UnifyApps platform and the external service are not significantly out of sync (relevant for TOTP and JWT-based auth)
Contact Support
If the issue persists after working through the steps above, contact the UnifyApps support team at support@unifyapps.com. Include the connection type, the HTTP status code and error message from the error panel, and the steps already attempted.
Tip: Before contacting support, use the "Copy error details" option in the error panel (if available) to capture the full error payload — this significantly speeds up diagnosis.
Notes
Keep the following in mind when troubleshooting connection errors:
Start with the error panel (HTTP status code and error message) before attempting any fix; the status code narrows the problem category immediately.
401/403 errors almost always indicate a credential or scope issue; 408/504 indicates a network or timeout issue — treat them as different root causes.
Before contacting support, work through all General Sanity Checks and record which steps you completed; this significantly speeds up diagnosis.
Re-entering credentials from scratch (rather than editing an existing connection) resolves a high proportion of authentication errors.
For OAuth connections, revoke any cached tokens in the external application before starting a fresh authorization flow.