Manage Salesforce integration API calls and sync errors

The HubSpot-Salesforce integration may encounter sync errors which prevent data from syncing. You can identify and resolve these sync errors in your Salesforce integration settings.

Adjust API call limit

• In your HubSpot account, click the settings settings icon in the top navigation bar. In the left sidebar menu, navigate to Integrations > Connected Apps.
• In the list of connected apps, click Salesforce. 
• Click the Sync Health tab. 
• In the API call use section, you'll see how many API calls you've used in the last 24 hours. The Limited by Salesforce number is the amount of API calls you can make based on your Salesforce settings. To adjust how many of those calls can be allocated to HubSpot, edit the Allocated to HubSpot field. 

View Salesforce sync errors

• In your HubSpot account, click the settings settings icon in the top navigation bar. In the left sidebar menu, navigate to Integrations > Connected Apps.
• In the list of connected apps, click Salesforce. 
• Click the Sync Health tab. 
• Under Sync errors, you'll see cards for each error type, with the number of current errors and impacted records for each. Click an error type card to see details of the errors in the right panel. Learn more about each error type and resolution recommendations. 

• To see more details for an error, click the info icon info in the Error Type column.
• To take action on individual records, click [#] records in the Affected Records column, then click Create view to create a filtered view of the impacted records. 
• Once you have resolved the errors, return to the Associations errors list. Select the checkbox to the left of any resolved errors and click Resync.
• To export your errors, click Export errors in the top right.

Salesforce sync errors types

Associations

Examples of associations errors 

• Association limit reached
• Waiting for account to sync

What the errors mean

Records aren't syncing because they are associated with Salesforce Accounts that haven't synced to HubSpot Companies yet, or because they are associated with records that have hit HubSpot's record association limit. 

How to resolve the errors 

To resolve the Association limit reached error, you can either remove some of the associated records or associate them with a different Salesforce record, and then proceed with the sync.

To resolve the Waiting for account to sync error, it's recommended you run an import of Salesforce Accounts. 

Custom code

Examples of custom code errors 

• Salesforce automation
• Missing contact ID
• Salesforce custom field validation rule
• Salesforce flow

What the errors mean

Records aren't syncing due to an issue caused by automation, flows, or validation rules in your Salesforce account.

How to resolve the errors

Duplicates

Examples of duplicates errors

• Email already in use
• Salesforce duplicate rule

What the errors mean

A Salesforce lead or contact can't sync to HubSpot because the email address already exists on a HubSpot contact record or due to a deduplication rule in Salesforce. 

How to resolve the errors

To resolve the Email already in use error, remove the email address from the existing HubSpot contact.

To resolve the Salesforce duplicate rule error, it's recommended that you check the matching rules for deduplication you set up in Salesforce. 

Permissions

Examples of permissions errors

• Insufficient access or missing Salesforce record
• Salesforce field permission
• Insufficient Salesforce access

What the errors mean

Changes made in HubSpot cannot sync to Salesforce because the connected user does not have access to the necessary field or object in Salesforce.

How to resolve the errors

In most cases, the Insufficient access or missing Salesforce record error occurs when the integration attempts to update a Salesforce field with an incorrect value or create an incorrect association. 

To resolve the Salesforce field permission error, ensure that the Salesforce integration user has Read and Edit permissions to the field in Salesforce. 

The Insufficient Salesforce access error occurs when the Salesforce integration user cannot perform the action in Salesforce due to their user permissions in Salesforce. It's recommended that you check the Salesforce integration user permissions in Salesforce.

Picklists

Examples of picklists errors

• Missing Salesforce picklist option
• Mismatched state or country value
• Mismatched options
• Inactive Salesforce owner
• Restricted picklist value
• Inactive opportunity stage
• Salesforce owners not synced
• Option limit exceeded
• Default sales process unavailable
• Missing or invalid opportunity stage

What the errors mean

Records aren't syncing due to a discrepancy between picklist field values in HubSpot and Salesforce. This can happen when a picklist value in one system does not match any current values in the other, if the picklist has hit a limit of values, or if the value passed is not valid.

How to resolve the errors

To resolve the Mismatched state or country value error, it's recommended that you check that the following requirements are met:

• The internal value of the Country property option in HubSpot must match an existing Country option in your State and Country/Territory picklist settings in Salesforce. 
• The State value must exist as an Available State/Province option for the record's Country value in Salesforce. In addition, the internal value of the State property option in HubSpot must match an existing State option in Salesforce. 

To resolve the Mismatched options error, it's recommended that you update the internal/API name of the Salesforce field options to match the internal value of the property options in HubSpot. 

To resolve the Inactive Salesforce owner error, reassign the HubSpot record to a user that's an active user in Salesforce. 

The Restricted picklist value error occurs when you have the Restrict picklist to the values defined in the value set setting turned on for the field in Salesforce. When this is turned on in Salesforce, the value that you're trying to sync from HubSpot to Salesforce must exist as an option in the Salesforce picklist. It's recommended that you turn off the Restrict picklist to the values defined in the value set setting in Salesforce, so that any values can sync from HubSpot to Salesforce. 

The Inactive opportunity stage error occurs when a Salesforce opportunity with an inactive opportunity stage attempts to sync to HubSpot. To resolve this error, change the opportunity stage in Salesforce to active or move the opportunity to an active stage. 

To resolve the Salesforce owners not synced error, ensure that the Salesforce users have User Type set to Standard, Power Partner, or Guest in Salesforce. 

To resolve the Option limit exceeded error, it's recommended that you delete extra property options in HubSpot and Salesforce that your team isn't using. In addition, ensure that all mapped properties have corresponding field types. 

In most cases, the Default sales process unavailable error occurs when Salesforce opportunities attempt to sync to HubSpot with a missing Record Type. If you have turned on Record Types in Salesforce, but you aren't using them, or have Salesforce opportunities without a Record Type, it's recommended that you work with Salesforce to deactivate all Record Types or create a new Record Type. 

To resolve the Missing or invalid opportunity stage error, ensure that the Salesforce opportunity's stage value exists in the HubSpot pipeline. 

Property mappings

Examples of property mappings errors 

• Type mismatch
• Missing Salesforce ID
• Invalid Salesforce ID

What the errors mean

Records aren't syncing because of a discrepancy in the mapping between the HubSpot property and the Salesforce field. This can mean that the property and field types are not compatible, that the property or field no longer exists, or that a Salesforce reference field mapping needs to be created.

How to resolve the errors 

To resolve the Type mismatch error, ensure that the property type in HubSpot and the field type in Salesforce are compatible. Learn more about the HubSpot property field types that can sync to Salesforce. 

The Missing Salesforce ID error occurs when HubSpot tried to sync a value other than an existing Salesforce ID to a reference/lookup field in Salesforce. 

To resolve the Invalid Salesforce ID error, it's recommended that you check the custom validation rule that you have set up in Salesforce. 

Property values

Examples of property values errors

• String too long
• Invalid email
• Missing required country
• Invalid value
• Owner assignment
• Restricted unique value
• Missing required value

What the errors mean

Records aren't syncing between HubSpot and Salesforce because they include property values that are not valid. These errors typically require that the individual affected records are updated to correct the error.

How to resolve the errors

To resolve the String too long error, shorten the field value in Salesforce or HubSpot, or increase the character limit of the field in Salesforce. 

To resolve the Invalid email error, update the email address formatting on the Salesforce record that's attempting to sync to HubSpot.

To resolve the Missing required country error, it's recommended that you check that the following requirements are met:

• The internal value of the Country property option in HubSpot must match an existing Country option in your State and Country/Territory picklist settings in Salesforce. 
• The State value must exist as an Available State/Province option for the record's Country value in Salesforce. In addition, the internal value of the State property option in HubSpot must match an existing State option in Salesforce. 

To resolve the Invalid value error, it's recommended that you update the property value on the Salesforce record to meet the HubSpot's requirements for the property value. 

In most cases, the Owner Assignment error occurs when a HubSpot activity syncs to Salesforce as a Salesforce task and HubSpot attempts to assign the task to a Salesforce Queue owner.

To resolve the Restricted unique value error, it's recommended that you check the matching rules for deduplication you set up in Salesforce. 

To resolve the Missing required value error, add a value to the Salesforce record for any property that is marked as required in HubSpot. 

Other

Records aren't syncing due to an unknown error. Please contact HubSpot Support for further assistance with these errors.

Please note: it is possible to bulk resync 100 Salesforce errors at a time. To sync more than 100 errors, import the records from Salesforce or update a mapped property.

Set up sync error notifications

• In your HubSpot account, click the settings settings icon in the top navigation bar. In the left sidebar menu, navigate to Integrations > Connected Apps.
• In the list of connected apps, click Salesforce. 
• Click the Sync Health tab. 
• Under Sync errors, click Manage notifications. 
• In the dialog box, click to toggle the Turn on notifications switch on. 
• Select the radio button next to Instantly, Daily, or Weekly to set the frequency of your notifications. 
• Click Save.