Error Handling
Part of Marketing automation integrations
Checking a marketing connector's behaviour after a failed contact update
Inspect the destination record, sync status, mapping and next retry after a marketing connector fails to update a contact.
After a failed contact update, inspect the destination record, the connector's status for that record and any pending attempt before changing configuration. An error describes an attempt; it may not establish whether the destination changed or what the connector will do next.
Reconstruct the update
Identify the source contact, the intended destination record, the fields and the time of the attempt. Compare intended values against the destination's current values. Check the connector's reported record state, using the terms that product exposes.
HubSpot data sync is one example. Its internal index tracks record states as syncing, failing or excluded. It compares records with its copy, and can recover dropped or errored API calls or endpoints. Other connectors may expose different controls, or only an API response or run log.
Find the cause before rerunning
Check the attempted property, destination type, accepted options, permissions, matching key and sync direction. HubSpot Contacts APIs reject enumeration values outside a property's defined options; resending the same invalid value will not fix that error. HubSpot data sync also documents one-way limits for some dropdown mappings, and for fields constrained by a third-party API or read-only setting.
An excluded record may fail a sync filter or lack a usable identifier. A queued record needs a check of whether the existing work is progressing. For a timeout with an uncertain outcome, inspect the destination before initiating another update.
Common Causes of Failed Contact Updates and Their Resolution
- Invalid enumeration valueSending a non-permitted dropdown option (e.g., 'Premium' when only 'Basic', 'Standard' allowed).
- Missing or incorrect matching keyNo valid email or unique identifier in the record to link it across systems.
- Read-only or third-party constrained fieldField mapped from a system that doesn’t allow updates (e.g., ATO-assigned ABN fields via external API).
- Sync filter exclusionRecord fails due to business logic or segmentation rules (e.g., not in active marketing list).
- API timeout or network failureUncertain outcome; requires inspection of the destination before retrying.
Check the next action and final value
Determine whether the chosen connector retries automatically, requires an operator rerun or has stopped after a validation error. If it exposes a next-attempt time, record it. Correct the specific cause, such as missing access or wrong record pairing. Review other records before changing a mapping they share.
After the correction, follow the affected contact through another attempt and inspect the destination value. Confirm the intended property arrived and the record no longer shows a failure. Check that an older queued attempt has not overwritten a newer value.
A controlled check can use one contact. Inspect how the chosen connector labels the outcome, whether it retries and what the destination shows after correction.
Pre-Retry Validation Checklist After a Connector Failure
- Check if manual rerun is requiredIf the connector has paused due to an invalid value, a manual correction is needed before resuming.
- Review shared mappings for other recordsChanging a field mapping may affect multiple contacts; test on one first.
- Verify no older queued attempt overwrote new dataEnsure the latest update wasn't lost during reprocessing.
- Inspect final destination value post-correctionConfirm the correct field value appears and the record no longer shows as failed.
