HubSpot Troubleshooting
Diagnose and resolve HubSpot CRM integration issues
Platform administrators can diagnose and assist with HubSpot integration issues.
Common Issues
Authentication & Connection
OAuth token issues
Symptoms:
- Integration disconnected
- 401 errors in sync logs
Resolution:
- Check token expiry in integration status
- Verify HubSpot app hasn't been uninstalled
- Re-authorize through Client Portal if needed
- Verify OAuth scopes match requirements
API rate limiting
Symptoms:
- 429 Too Many Requests errors
- Syncs completing partially
Resolution:
- Check HubSpot API usage in their portal
- Review sync frequency settings
- Implement backoff if hitting limits
- Consider upgrading HubSpot plan for higher limits
Data Sync Issues
Contacts not syncing
Common causes:
- Duplicate detection blocking
- Required properties missing
- Property doesn't exist in HubSpot
Troubleshooting:
- Check HubSpot duplicate management settings
- Verify all mapped properties exist
- Review property mapping configuration
- Check sync error logs for specific issues
Company association issues
Common causes:
- Company not found in HubSpot
- Association type not configured
- Multiple companies with same domain
Troubleshooting:
- Verify company exists or needs to be created first
- Check association mapping settings
- Review company matching rules (by domain, name)
List membership not updating
Common causes:
- List is static (not dynamic)
- Contact doesn't meet list criteria
- List enrollment automation disabled
Troubleshooting:
- Verify list type in HubSpot
- Check list criteria/filters
- Review automation settings in integration
Engagement Tracking Issues
Activities not appearing in timeline
Common causes:
- Engagement type not supported
- Timeline API permissions missing
- Custom timeline event type not configured
Troubleshooting:
- Verify timeline event type is created in HubSpot
- Check OAuth scopes include timeline permissions
- Review engagement type mapping
Diagnostic Endpoints
Connection Status
GET /api/admin/integrations/hubspot/{organization_id}/status
Authorization: Bearer {admin_token}Response:
{
"connected": true,
"hub_id": "12345678",
"portal_name": "Example Organization",
"token_expires_at": "2025-01-15T16:00:00Z",
"scopes": ["contacts", "companies", "timeline"],
"last_sync": "2025-01-15T10:30:00Z",
"sync_stats": {
"contacts_synced": 892,
"contacts_failed": 5,
"companies_synced": 234,
"engagements_synced": 4521
},
"rate_limit": {
"daily_limit": 500000,
"daily_used": 12534,
"secondly_limit": 100
}
}View Sync Errors
GET /api/admin/integrations/hubspot/{organization_id}/errors
Authorization: Bearer {admin_token}Response:
{
"errors": [
{
"id": "err-uuid-1",
"type": "contact_sync",
"hubspot_error": "PROPERTY_DOESNT_EXIST",
"property": "custom_field_xyz",
"record_id": "member-uuid",
"timestamp": "2025-01-15T09:15:00Z"
}
],
"total": 5,
"page": 1
}Retry Failed Records
POST /api/admin/integrations/hubspot/{organization_id}/retry
Authorization: Bearer {admin_token}
Content-Type: application/json
{
"error_ids": ["err-uuid-1", "err-uuid-2"]
}Verify Property Mapping
GET /api/admin/integrations/hubspot/{organization_id}/property-mapping
Authorization: Bearer {admin_token}Response:
{
"contact_properties": [
{
"memberpulse_field": "email",
"hubspot_property": "email",
"status": "valid"
},
{
"memberpulse_field": "membership_type",
"hubspot_property": "membership_tier",
"status": "valid"
},
{
"memberpulse_field": "custom_field",
"hubspot_property": "custom_xyz",
"status": "invalid",
"error": "Property does not exist in HubSpot"
}
]
}Escalation
For complex HubSpot issues:
- Collect organization ID, HubSpot portal ID, error details
- Check HubSpot system status page
- Review HubSpot API changelog for breaking changes
- Escalate to development team with diagnostic output