Connection Health & Troubleshooting

Overview

This guide covers monitoring the health of your connected integrations and troubleshooting common issues.

Integration Health Dashboard

The Integrations dashboard provides a centralized view of all your connections:

• Connection Status: Active/Inactive indicators for each integration
• Last Sync: Timestamp of last successful data synchronization
• API Limits: Usage vs. quota limits for each service
• Error Logs: Recent errors and warnings
• Webhook Logs: Incoming and outgoing webhook events

Access the dashboard via Admin → Integrations.

Common Issues and Solutions

1. Authentication Failures

Symptoms:

• Connection status shows "Inactive"
• Error messages like "Invalid credentials" or "Authentication failed"
• No data sync for extended periods

Causes:

• API keys or OAuth tokens expired or revoked
• Incorrect credentials entered during setup
• Permission changes in the connected service

Solutions:

1. Verify credentials in the integration settings
2. Re-authenticate the connection
3. Check permission scopes in the connected service
4. Regenerate API keys if necessary

2. Sync Failures

Symptoms:

• "Last sync" timestamp is outdated
• Data appears incomplete or missing
• Error logs show sync-related errors

Causes:

• Rate limiting or API quota exceeded
• Network connectivity issues
• Changes in the connected service's API
• Data format mismatches

Solutions:

1. Check API usage in the service's developer console
2. Verify network connectivity to the service
3. Review error logs for specific error codes
4. Adjust sync frequency or data volume
5. Update API versions if needed

3. Webhook Delivery Failures

Symptoms:

• Missing events (calls, SMS, appointments)
• Error logs show webhook delivery failures
• Events appear in the source system but not in af-gemini-connect

Causes:

• Incorrect webhook endpoint URLs
• SSL/TLS certificate issues
• Network firewalls blocking requests
• Payload size limits exceeded

Solutions:

1. Verify webhook endpoint URLs are correct
2. Check SSL certificates are valid and trusted
3. Ensure firewalls allow incoming webhook requests
4. Implement retry logic with exponential backoff
5. Compress large payloads if needed

4. Rate Limiting

Symptoms:

• Error messages like "Too many requests" or "Rate limit exceeded"
• Sudden cessation of data updates
• 429 HTTP status codes in error logs

Causes:

• Exceeding API rate limits
• Burst traffic patterns
• Shared quota across multiple integrations

Solutions:

1. Review rate limit policies in the service's documentation
2. Implement request throttling and queuing
3. Stagger sync operations to avoid peaks
4. Request quota increases if needed
5. Use webhooks instead of polling when possible

5. Data Format Changes

Symptoms:

• Sync errors after a service updates its API
• Missing or malformed data fields
• Schema validation failures

Causes:

• Connected service changed their API response format
• Field names or data types changed
• Required fields were added or removed

Solutions:

1. Review the service's API changelog
2. Update field mappings and transformations
3. Implement backward compatibility where possible
4. Test changes in a staging environment first

Proactive Monitoring

Set Up Alerts

Configure automated alerts for critical integration events:

• Connection failures — Immediate notification
• Sync failures — Immediate notification
• API quota warnings — When usage exceeds 80% of limit
• Webhook failures — After 3 consecutive delivery failures

Regular Health Checks

Perform routine maintenance:

1. Daily:

   • Check the integrations dashboard for any red/yellow indicators
   • Review error logs for new entries
   • Verify critical syncs completed successfully

2. Weekly:

   • Review API usage reports
   • Check for service updates or API changes
   • Test webhook endpoints with sample payloads

3. Monthly:

   • Audit all integration configurations
   • Update API keys and refresh tokens
   • Review permission scopes and adjust as needed
   • Test failover and recovery procedures

Implement Circuit Breakers

Use circuit breaker patterns to prevent cascading failures:

• Closed: Integration is healthy, requests flow normally
• Open: Integration is failing, requests are blocked
• Half-Open: Test phase after recovery, requests limited

This prevents a failing integration from overwhelming your system.

Recovery Procedures

Reconnecting a Failed Integration

1. Identify the root cause from error logs
2. Fix the underlying issue (update credentials, adjust settings, etc.)
3. Test the connection in a staging environment if possible
4. Reconnect via the integration settings
5. Verify data sync is working correctly
6. Monitor closely for 24-48 hours after reconnection

Rolling Back Changes

If a recent change caused integration issues:

1. Revert the configuration to the previous working state
2. Document the rollback in your change log
3. Investigate the issue in a test environment
4. Implement a fix and test thoroughly
5. Deploy the fix with proper monitoring

Emergency Disconnect

In rare cases, you may need to immediately disconnect an integration:

1. Access the integration settings
2. Click Disconnect for the problematic integration
3. Notify affected users about the service disruption
4. Implement manual workarounds if needed
5. Begin recovery procedures as soon as possible

Service-Specific Considerations

GoHighLevel (GHL)

• Token expiration: GHL API tokens expire every 60 days
• Webhook endpoints: Ensure your server is publicly accessible
• Rate limits: 100 requests per minute per account
• Field sync: Custom fields may need manual mapping

Google Services

• Quota management: Each Google API has different limits
• Token refresh: OAuth tokens can be long-lived but may need refresh
• Property permissions: Ensure you have admin access to all properties
• API versioning: Be prepared for API version deprecation

Meta Ads

• App review: Required for production use, can take days
• Token expiration: System user tokens expire and need refresh
• Rate limits: Strict limits on ad creation and management
• Business verification: May be required for some permissions

Google Ads

• Manager accounts: Required for managing multiple client accounts
• Token refresh: OAuth tokens need periodic refresh
• Developer token: Required for API access
• Usage limits: Monthly spend limits may affect API access

Getting Help

If you can't resolve an integration issue:

1. Check the documentation for the specific service
2. Review error logs for specific error codes
3. Search the knowledge base for similar issues
4. Contact support with detailed information:
   • Integration name and ID
   • Error messages and codes
   • Steps to reproduce
   • Screenshots or logs

FAQ

Q: How do I know if an integration is healthy?
A: Check the integrations dashboard for green status indicators and recent sync timestamps.

Q: What should I do if an integration fails?
A: First check the error logs for specific issues, then follow the troubleshooting steps for that integration.

Q: Can I schedule maintenance windows?
A: Yes, you can schedule syncs during off-peak hours to minimize impact.

Q: How do I set up alerts?
A: Configure alert rules in the Admin → System Settings → Alerts section.

Q: What's the most common integration issue?
A: Authentication failures due to expired tokens or changed credentials.