Overview
This comprehensive resource will help you diagnose and resolve connection issues when setting up integrations with external services. Whether you're connecting to APIs, databases, or third-party platforms, this guide covers common challenges and their solutions.
API Timeout Issues
API timeouts occur when the connection attempt to the target service exceeds the maximum allowed time. These timeouts are critical protection mechanisms that prevent system resources from being tied up indefinitely but can indicate underlying connectivity or configuration issues that need to be addressed.
Potential Causes
Network connectivity issues
Firewall restrictions
Service availability problems
Solutions
There are multiple ways in which you can enable access and resolve timeout issues:
IP Whitelisting
Add your UnifyApps IP addresses to the target service's allowlist
Verify firewall rules aren't blocking the connection
Ensure all necessary ports are open
SSL Certificate Configuration
Verify that the SSL certificate is valid and not expired
Ensure the certificate chain is complete
Check if the target service requires specific SSL/TLS versions
SSH Tunnel Setup
Configure SSH tunnel for secure connectivity
Verify SSH key permissions
Ensure the tunnel endpoint is correctly specified
Incorrect Input Details
This section encompasses a broad category of errors that arise when the provided configuration parameters don't match the expected format or requirements of the target service. This can range from malformed URLs to invalid authentication tokens. These errors are often immediately detectable and typically return specific error messages that can help identify the exact nature of the misconfiguration.
Potential Causes
Authentication Credentials
Invalid API keys or tokens
Expired Credentials
Incorrect authentication type selected
Configuration Parameters
Wrong endpoint URLs
Incorrect port numbers
Invalid service-specific parameters
Solutions
Verify Credentials
Double-check API keys and tokens
Ensure credentials have proper permissions
Regenerate tokens if necessary
Validate Configuration
Confirm endpoint URLs are correct and accessible
Verify port numbers match service requirements
Check service-specific documentation for parameter formats
Mandatory Fields Not Filled
This error type occurs when required configuration fields are left empty. Each integration type in UnifyApps has specific required parameters that must be properly configured for the connection to be established. These fields are fundamental to the connection setup and are typically marked with an asterisk (*) in the user interface. Missing mandatory fields prevents the connection from being saved or established, serving as a validation checkpoint before any connection attempt is made.
Solutions
Field Validation
Review all required fields marked with asterisks (*)
Ensure no empty required fields
Verify format of the entered data matches the requirements
Service-Specific Requirements
Check service documentation for mandatory parameters
Validate field format requirements
Ensure all dependent fields are properly configured
OAuth Redirection Issues
OAuth redirection errors are specific to connections that utilise OAuth authentication flows. These errors occur when there's a mismatch between the redirect URLs configured in the OAuth provider's settings and the URLs expected by UnifyApps. This critical security feature of OAuth ensures authentication callbacks are only processed for pre-approved URLs.
Potential Causes
Authentication Credentials
Invalid API keys or tokens
Expired Credentials
Incorrect authentication type selected
Configuration Parameters
Wrong endpoint URLs
Incorrect port numbers
Invalid service-specific parameters
Solutions
Verify Credentials
Double-check API keys and tokens
Ensure credentials have proper permissions
Regenerate tokens if necessary
Validate Configuration
Confirm endpoint URLs are correct and accessible
Verify port numbers match service requirements
Check service-specific documentation for parameter formats
Debugging your issues
When an error occurs, a red alert banner will appear at the top of your connection configuration screen to notify you of the issue.
Look for the specific error message in the alert banner, which briefly describes what went wrong during the connection attempt.
Use the "
Show Details" button to open an expanded error panel on the right side of your screen.
The expanded error panel directly displays the complete error response from the service you're trying to connect to.
Review the technical details in the error panel, which include HTTP status codes, timestamps, and service-specific error messages.
You can follow some general sanity checks, such as:
Verify that all required fields in your connection configuration have been filled out correctly.
Double-check that your authentication credentials (tokens, keys, passwords) are current and have not expired.
Ensure that any URLs or endpoints you've entered match exactly what's specified in the service's documentation.
Test your credentials directly in the service's console or dashboard to confirm they're working correctly.
Consider testing the connection with different authentication methods if multiple options are available.
Review your network settings to ensure there are no firewall rules blocking the connection.
Finally, please reach out to support@unifyapps.com if you've tried the troubleshooting steps above but are still experiencing issues.