Integration Troubleshooting

Common issues and solutions when setting up integrations with Aim.

General Troubleshooting Steps

Before diving into integration-specific issues, try these general troubleshooting steps:

1. Check Integration Status

1. Go to Settings → Integrations
2. Find your integration
3. Check the status indicator:
   • 🟢 Connected - Working normally
   • 🟡 Warning - Partial issues, some data may not sync
   • 🔴 Error - Connection failed, needs attention

2. Review Sync Logs

1. Click on your integration name
2. Go to Sync History tab
3. Review recent sync attempts
4. Look for error messages or patterns

3. Test Connection

1. Open integration settings
2. Click Test Connection
3. Review detailed error message if test fails

4. Verify Credentials

• Check that API keys/tokens haven’t expired
• Ensure passwords haven’t changed
• Verify service account keys are still valid
• Confirm OAuth tokens haven’t been revoked

5. Check Permissions

• Ensure your account still has necessary permissions in the source system
• Verify service accounts still have required roles
• Check that app permissions haven’t been revoked

Google Analytics

Permission Denied Error

Error: 403 Forbidden or “Permission denied”

Causes:

• Service account not added to GA4 property
• Incorrect email address used
• Viewer role not assigned

Solutions:

1. Verify Service Account Email

Open your JSON key file and find the client_email:

{
  "client_email": "your-service-account@project-id.iam.gserviceaccount.com"
}

2. Check GA4 Access

1. Go to GA4 Admin → Property Access Management
2. Search for your service account email
3. Verify it’s listed with “Viewer” role
4. If not found, add it again

3. Wait for Propagation

After adding the service account, wait 5-10 minutes for permissions to propagate, then test again.

Organization Policy Blocks Key Creation

See the detailed troubleshooting section in the Google Analytics integration guide.

Invalid Property ID

Error: “Property not found” or 404

Solution:

1. Go to GA4 Admin → Property Settings
2. Copy the Property ID (numeric value at top)
3. Update your Aim integration with the correct ID

No Data After Sync

Causes:

• GA4 property has no data
• Date range issue
• Metrics not properly configured

Solutions:

1. Verify data exists in GA4 for the time period you’re querying
2. Check Aim metric date ranges (default is last 30 days)
3. Try manual refresh: Systems → Connection → Sync Now

Salesforce

Authentication Failed

Error: “Invalid username, password, security token, or user locked out”

Solutions:

1. Check credentials:

   • Username must be complete email address
   • Password must be current
   • Security token must be appended to password

2. Reset security token:

   • Log into Salesforce
   • Go to Settings → Reset My Security Token
   • Check your email for the new token
   • Update Aim with Password + Token

3. Check IP restrictions:

   • Salesforce may block API access from new IPs
   • Add Aim’s IP addresses to trusted list
   • Or use OAuth instead of username/password

API Limit Exceeded

Error: “REQUEST_LIMIT_EXCEEDED”

Causes:

• Too many API calls within 24-hour period
• Multiple integrations using same Salesforce org

Solutions:

1. Reduce sync frequency (daily instead of hourly)
2. Limit number of objects being synced
3. Upgrade Salesforce API limits
4. Coordinate with other tools using the API

Snowflake

Network Error / Connection Timeout

Error: “Unable to connect to Snowflake” or timeout errors

Causes:

• Firewall blocking connection
• Incorrect account identifier
• Network policy restrictions

Solutions:

1. Verify account identifier:

   • Format: <account>.<region>.snowflakecomputing.com
   • Example: xy12345.us-east-1.snowflakecomputing.com
   • Check in Snowflake web UI URL

2. Check network policy:

   SHOW NETWORK POLICIES;

   Add Aim’s IP addresses if restricted.

3. Test connectivity:

   telnet <account>.snowflakecomputing.com 443

Authentication Failed

Error: “Incorrect username or password” or “Invalid credentials”

Solutions:

1. Verify credentials:

   • Username is case-insensitive
   • Password is case-sensitive
   • Check for extra spaces

2. Check user permissions:

   SHOW GRANTS TO USER <username>;

   User needs USAGE on warehouse and database, SELECT on schemas/tables.

3. Reset password if needed:

   ALTER USER <username> SET PASSWORD='<new_password>';

Stripe

Invalid API Key

Error: “Invalid API Key provided”

Solutions:

1. Check key format:

   • Must start with sk_live_ (production) or sk_test_ (test mode)
   • Ensure entire key was copied (no spaces or truncation)

2. Verify key is active:

   • Go to Stripe Dashboard → Developers → API Keys
   • Ensure key hasn’t been revoked
   • Generate new key if needed

3. Check mode:

   • Test mode keys don’t work with live data
   • Use live keys for production data

Rate Limit Exceeded

Error: 429 Too Many Requests

Solutions:

1. Reduce sync frequency
2. Limit date ranges for historical data imports
3. Contact Aim support to optimize queries

HubSpot

OAuth Token Expired

Error: “Token has been revoked” or “Token expired”

Solutions:

1. Reauthorize:

   • Go to Settings → Integrations → HubSpot
   • Click Reconnect
   • Complete OAuth flow again

2. Check app permissions:

   • Verify HubSpot app is still installed
   • Go to HubSpot Settings → Integrations → Connected Apps
   • Ensure Aim app is listed and active

Missing Scopes

Error: “This access token doesn’t have the required scopes”

Solution:

1. Reauthorize the connection (will request updated scopes)
2. If error persists, contact Aim support (we may have added new features)

Slack

Webhook Not Receiving Messages

Causes:

• Webhook URL changed
• Channel was deleted
• App uninstalled from workspace

Solutions:

1. Test webhook:

   curl -X POST -H 'Content-type: application/json' \
     --data '{"text":"Test from Aim"}' \
     <YOUR_WEBHOOK_URL>

2. Regenerate webhook:

   • Slack workspace settings → Apps → Incoming Webhooks
   • Create new webhook
   • Update in Aim

3. Check channel:

   • Verify channel still exists
   • Ensure app is added to channel: /invite @Aim

Database Connections (PostgreSQL, MySQL)

Connection Refused

Error: “Connection refused” or “Could not connect to server”

Causes:

• Database not accessible from internet
• Firewall blocking connection
• Wrong host/port

Solutions:

1. Check host and port:

   • Default PostgreSQL port: 5432
   • Default MySQL port: 3306
   • Verify in your database admin panel

2. Whitelist Aim IPs:

   • Add Aim’s IP addresses to your firewall/security group
   • Contact Aim support for current IP list

3. Test connection:

   # PostgreSQL
   psql -h <host> -p <port> -U <username> -d <database>
    
   # MySQL
   mysql -h <host> -P <port> -u <username> -p <database>

SSL/TLS Errors

Error: “SSL connection required” or certificate errors

Solutions:

1. Enable SSL in Aim connection settings
2. For self-signed certificates:
   • Contact Aim support to upload your CA certificate
3. Verify SSL is enabled on database server

Common Error Messages

”Rate limit exceeded”

Meaning: Too many API requests in a short period

Solutions:

• Reduce sync frequency
• Limit number of metrics
• Wait and retry later
• Upgrade to higher tier (if source system has paid tiers)

“Unauthorized” or “401 Error”

Meaning: Authentication failed

Solutions:

• Verify credentials are correct
• Check if credentials have expired
• Ensure API keys/tokens haven’t been revoked
• Re-authenticate OAuth connections

”Forbidden” or “403 Error”

Meaning: Authenticated but don’t have permission

Solutions:

• Check user permissions in source system
• Ensure required roles are assigned
• Verify service account has necessary access
• Check IP whitelist if applicable

”Not Found” or “404 Error”

Meaning: Resource doesn’t exist

Solutions:

• Verify IDs are correct (project ID, account ID, etc.)
• Check that resources haven’t been deleted
• Ensure you’re querying the right environment (prod vs test)

“Timeout” or “Gateway Timeout”

Meaning: Request took too long

Solutions:

• Reduce date ranges
• Limit number of metrics/objects
• Check source system status
• Try again during off-peak hours

Getting Help

Before Contacting Support

Gather this information:

1. Integration name (e.g., “Google Analytics”, “Salesforce”)
2. Connection name in Aim
3. Exact error message
4. Steps to reproduce
5. When the issue started
6. Recent changes (if any)

Check System Status

1. Visit status.aimmetrics.ai for service status
2. Check source system status pages:
   • Google Cloud Status
   • Salesforce Status
   • Stripe Status
   • AWS Status

Contact Support

• Email: support@aimmetrics.ai
• In-app chat: Click the chat icon in bottom right
• Community: Aim Community Slack

Include all the information you gathered above for fastest resolution.

Emergency Issues

For critical production issues:

• Email: urgent@aimmetrics.ai
• Include “URGENT” in subject line
• Describe business impact

Preventive Maintenance

Best Practices

1. Monitor regularly:

   • Check integration status weekly
   • Review sync logs for warnings
   • Set up sync failure alerts

2. Keep credentials fresh:

   • Rotate API keys every 90 days
   • Update passwords proactively
   • Refresh OAuth tokens before expiration

3. Document changes:

   • Note when you modify integrations
   • Keep track of credential updates
   • Document any custom configurations

4. Test after changes:

   • Test connections after updating source systems
   • Verify data after major source system upgrades
   • Re-test after changing permissions

5. Stay informed:

   • Subscribe to source system status updates
   • Follow Aim release notes
   • Watch for deprecation notices

Related Resources

• Integration overview
• Google Analytics setup
• Contact support
• FAQ