The result is a starting point, not a diagnosis. Use it to avoid unnecessary resets, remapping work, or full-history reruns before you have read the actual error.
It is most useful for small teams managing routine CRM, accounting, HR, support, inventory, or operations workflows. It is less useful when the failure is already explicit in a platform error message or when a vendor has confirmed an account-wide incident.
Start With the Point Where the Sync Failed
Most sync failures fall somewhere in a short chain:
- The source system creates or changes a record.
- The integration detects that change and starts a job.
- The integration authenticates and sends data to the destination.
- The destination accepts, rejects, or partially processes the request.
- A worker, queue, or retry process completes the job.
The most useful clue is usually the first stage that failed. A record that never triggered a job needs a different response than a record that reached the destination and was rejected for an invalid field value.
Before changing credentials, mappings, filters, or automation rules, save:
- The exact error text and error code
- The first failed timestamp, including time zone
- Whether every record failed or only a subset
- The affected object, such as contacts, invoices, tasks, or employee records
- Recent changes to credentials, permissions, field mappings, API versions, filters, or automation rules
- A run ID, request ID, job ID, or affected record ID
Avoid a broad rerun before capturing this information. A full rerun can overwrite the original error trail. It can also create duplicates if the destination accepted the first request but the integration failed before recording success.
The picker relies most heavily on failure scope, timing, error family, and recent changes. For example, every object failing immediately after an authorization update points toward access. Failures limited to records with a new status value point toward mapping or validation.
Match the Failure Pattern to the Likely Cause
“Records did not sync” is an outcome, not a diagnosis. The same message can describe an expired token, a rejected field value, a delayed queue, a blocked webhook, or a platform incident.
| Observed pattern | Cause family to prioritize | First evidence to review | Avoid doing first |
|---|---|---|---|
| Every sync fails after a credential renewal, user change, or account update | Authentication or authorization | Token expiration, connected account, OAuth grant, user status, permission changes | Rebuilding mappings or resyncing all history |
| Only certain records fail while others continue | Field mapping or validation | Rejected field name, required value, data type, picklist value, related record | Refreshing credentials without reading the rejected field |
| Failures rise during high-volume imports or scheduled batch jobs | API quota, rate limit, or queue backlog | HTTP 429 responses, retry schedule, job delay, request volume | Launching another large batch |
| Source records change but no sync job starts | Webhook, trigger, or filter issue | Event delivery log, trigger conditions, changed-record filters | Editing destination mappings |
| Records update in both systems but values keep reverting | Conflict rule, ownership, or cursor logic | Source-of-truth setting, update timestamps, conflict policy | Repeated manual corrections in both systems |
| Several unrelated integrations fail at the same time | Platform, network, or account-wide incident | Status page, account suspension notice, IP allowlist, DNS, or gateway errors | Resetting every connection independently |
| A scheduled sync fails but a manual run succeeds | Schedule-specific authentication, filter, queue, or cursor issue | Scheduled job settings, time zone, saved filter, retry rules, error history | Assuming the manual run fixed the scheduled workflow |
Error codes matter because similar-looking access failures have different fixes.
A 401 means the request lacks valid authentication. Common causes include an expired token, revoked connection, or invalid credentials.
A 403 means authentication succeeded, but the connected identity lacks permission for the requested action. Reconnecting an account does not grant missing object-level or field-level permissions.
A 429 means the receiving API rejected requests because its request threshold was reached. Reduce request pressure and follow the integration’s retry behavior rather than sending another large batch.
A queue delay is different from a 429. Queue delays mean jobs are waiting to run. That points toward worker health, job concurrency, or an upstream dependency holding the queue.
Keep the Workflow Simple Where It Matters
More fields, more triggers, and two-way updates create more ways for a sync to fail.
A one-way sync with clear field ownership is easier to maintain because only one system writes each field. The limitation is straightforward: edits made in the other system will not stay aligned.
Two-way synchronization needs explicit rules for:
- Which system owns each shared field
- How conflicting updates are handled
- Which timestamp determines the newer value
- What happens when a record is deleted
- How duplicates are identified
- Whether related records must exist before a child record can be created
Without those rules, both systems can keep overwriting each other.
Logging needs the same discipline. Full request and response payloads can expose field-level failures, but they can also expose customer contact details, payroll records, and financial data. Routine logs are more useful when they clearly capture run IDs, timestamps, object IDs, field names, status codes, and validation messages.
Reserve full payload captures for controlled incident work with appropriate access controls.
A full-history resync also creates problems of its own. It raises API volume, increases duplicate-record risk, and blends older data defects into the current incident. Start with one failed record or a narrow date range when that option is available.
Use Recent Changes to Narrow the Cause
The timing of a failure often matters as much as the error itself.
A sync that starts failing minutes after a permissions update belongs in the access queue first. A sync that breaks immediately after a new CRM field, accounting category, or intake-form value was introduced belongs in the field-validation queue first.
Work through the issue in this order:
-
Read the failed response. The error text usually identifies the system that rejected the request and the stage where the failure occurred.
-
Compare a failed record with a successful record. Look for blank required fields, new category values, malformed dates, overlong text, missing related records, or duplicate identifiers.
-
Review the latest configuration change. Inspect field mappings, filters, user roles, OAuth connections, webhook URLs, and scheduled job settings.
-
Inspect retry behavior. Repeated failures at regular intervals usually indicate a persistent permissions, validation, or mapping issue. A later successful retry points toward a temporary API, network, or queue event.
-
Retry a narrow scope. Use one record that failed and one that succeeded. This separates a record-level data problem from an account-wide connection problem.
A successful retry does not automatically close the incident. Event-driven integrations can miss a record when webhook delivery fails and no replay process exists. Polling integrations can skip changes when a saved cursor or last-run timestamp advances despite partial processing.
After a retry, confirm that the affected records reached the destination and contain the intended values.
Prevent Repeat Failures With Basic Integration Maintenance
Most integration failures appear around predictable changes: credentials expire, users leave, permissions change, new fields are added, and staff enter values that do not match a destination system’s rules.
Review active workflows on a recurring schedule. Focus on:
- Failed runs
- Rising retry counts
- Long processing delays
- Disabled automations
- New required fields
- Permission or connected-account changes
- Scheduled jobs that stopped running
- Repeated validation errors on the same field
A weekly review works for many small-business workflows. Revenue, payroll, inventory, and customer-support integrations need closer attention around business-critical deadlines.
Keep a compact register for every active connection:
- Business purpose and record types moved
- Source system and destination system
- Sync direction
- Account owner and backup owner
- Authentication method and renewal date
- Source-of-truth rule for each shared field
- Retry behavior and duplicate-control approach
- Escalation contact for each platform
This record is especially important when the original workflow builder is unavailable. It also prevents a common failure: an integration remains connected to a former employee’s account and stops when that account is deactivated.
Watch for Field, Permission, and API Mismatches
An integration only moves data that both systems can accept. Similar field names do not guarantee similar rules.
A field called “Start Date” in one system may accept a date with no time, while another expects a date-time value with a time zone. A currency field may reject text symbols or decimals beyond its allowed precision. A destination picklist may reject a new source value until the matching option exists.
Review these areas before changing a workflow:
- Identifiers: Choose whether email address, account ID, invoice number, or an external ID controls matching.
- Required fields: Confirm the destination can accept source records when optional source values are blank.
- Related records: Ensure parent accounts, projects, products, or owners exist before dependent records sync.
- Delete handling: Decide whether a source deletion archives, deletes, or leaves the destination record untouched.
- Field ownership: Assign one system as the authority for each shared field.
- API scope: Ensure the connected user can access the objects, fields, and actions used by the workflow.
- Network controls: Review IP allowlists, webhook endpoint certificates, and firewall rules that can block event delivery.
API retirements can break connectors that still call retired endpoints. API-version changes can also alter field behavior, pagination, required parameters, or authentication rules. Treat platform notices about API changes as scheduled maintenance work.
Before You Rerun a Failed Sync
Use this checklist before sending records again:
- Save the exact error, timestamp, and run or request ID.
- Identify whether the issue affects all records or a defined subset.
- Determine whether the source system, destination system, or integration layer rejected the process.
- Compare one failed record with one successful record.
- Review recent credential, permission, mapping, filter, and workflow changes.
- Look for 401, 403, 422, 429, timeout, duplicate, or validation messages.
- Confirm whether the destination received a partial record before retrying.
- Retry one record or a narrow date range before launching a broad resync.
- Record the final cause and the configuration change that resolved it.
How to Use the Picker Result
| Picker input | What it tells you | Likely first investigation |
|---|---|---|
| All records fail | The connection, account, platform, or workflow may be affected broadly | Authentication, authorization, API availability, queue state, or account status |
| Only some records fail | The connection is still working for at least part of the data set | Field validation, required values, related records, identifiers, or mapping rules |
| Failure began after a credential or user-account change | Access changed near the same time as the failure | Token status, OAuth grant, connected user, roles, and permissions |
| Failure began after a field, form, or status-value change | New source data may no longer match destination rules | Field mappings, picklists, data types, required fields, and field length |
| No job starts after a source record changes | The issue happened before data reached the destination | Webhook delivery, trigger conditions, filters, event subscriptions, or source automation |
| Jobs start but wait or fail during busy periods | Volume or processing capacity may be involved | API limits, retries, job concurrency, worker health, and queue backlog |
| Values repeatedly revert between systems | Both systems may be writing to the same field | Field ownership, conflict policy, timestamps, cursor behavior, and sync direction |
| Several integrations fail together | A shared dependency may be unavailable or blocked | Platform status, account status, network controls, DNS, gateway, or IP allowlist |
FAQ
Should a failed sync be rerun immediately?
No. Save the error and confirm whether the destination already received part of the request. A broad rerun can create duplicates, overwrite newer destination data, or hide the original failure pattern.
Start with a single failed record or a narrow date range.
What does it mean when only some records fail?
It usually points to a record-level data issue rather than a broken overall connection. Compare a failed record with a successful one and look for missing required fields, invalid status values, date formatting problems, duplicate identifiers, missing related records, or field-length limits.
Is a 401 error the same as a 403 error?
No. A 401 means the request lacks valid authentication, such as an expired token or revoked connection. A 403 means authentication succeeded but the connected account lacks permission for the requested object, field, or action.
Why does a sync work manually but fail on its schedule?
Scheduled jobs can use a different authentication context, saved filter, time window, or queue with separate retry rules. Review the scheduled job’s account connection, time zone, cursor logic, filter conditions, and error history.
How do you prevent duplicate records after an integration failure?
Use a stable external ID or idempotency key where the systems support one, and define one matching rule for each record type. Before retrying, search the destination by that identifier and inspect whether a partial create or update already occurred.
Bottom Line
Use the picker to narrow the investigation, then follow the evidence from the error code, affected-record pattern, and recent changes.
Access failures call for credential or permission work. Selective record failures call for mapping and validation work. Broad failures without a related workflow change call for API, queue, network, or platform-status investigation before anyone rebuilds the automation.