Troubleshooting: CRM integration sync error codes

A CRM integration on your dashboard — Salesforce, HubSpot, or a CDP destination (Braze, Iterable, Customer.io, Klaviyo) — reports a sync failure and the status stops tracking. Every failure one of these integrations raises collapses into one of three stable codes. Read error for the code first; the surface that raised it (an agent CRM tool, a queued activity-log item, an inbound contact-resolution call, or a CDP segment sync run) decides which recovery step to take.

Code	Meaning	Owner action
`CRM_CONNECTION_MISSING`	No active connection to this provider exists for your organization.	Re-install the integration from Settings → Integrations (see Reconnect).
`CRM_AUTH_EXPIRED`	The OAuth token the stored connection holds has expired, or was revoked on the CRM side.	Re-run the OAuth install once — the code clears on the next sync (see Reconnect).
`CRM_DISPATCH_FAILED`	A queued CRM activity or object-sync item could not dispatch to the provider — the CRM endpoint itself rejected or timed out on the outbound call.	Decode the provider’s underlying 4xx/5xx before re-queueing (see Dispatch failures).

Symptom

The integration card on Settings → Integrations reads disconnected or error, a CRM agent tool returns a { "ok": false, "error": "<code>" } result, an inbound contact-resolution call raises one of the codes, or a CDP segment sync run stamps one on its run record. The dashboard renders whichever failure the integration layer surfaced — it does not mean the CRM object never moved; it means one leg (connection, token, or dispatch) failed.

CRM integrations are fail-open: a revoked token or a down CRM endpoint never blocks an Orbit-side contact write. The failure marks the sync leg, and the failed item redrives once the connection is.

Locate the failing leg

Work top-down; the first hold tells you which route raised the code.

Agent CRM tools — Salesforce / HubSpot / Zendesk / Calendly / Intercom / Google Calendar / Microsoft 365 actions an LLM picks. The dispatch endpoint classifies transport errors into exactly these three codes and returns them in the tool result body as { ok: false, error: code, message } — every CRM agent tool failure is one of the three.
Inbound contact resolution — the Salesforce / HubSpot inbound resolution routes and the CDP POST /api/v1/cdp/crm-sync/run object-sync route raise the same codes when the tenant’s connection to the provider can’t be resolved or the outbound push rejects.
Queued activity-log items — model / call-synthesis pipelines enqueue CRM activity-log items; when the queued dispatch can’t reach the provider endpoint, CRM_DISPATCH_FAILED is stamped on the item. A backed-up queue of these items is transport, not auth.

Owner actions by code

Reconnecting (`CRM_CONNECTION_MISSING` / `CRM_AUTH_EXPIRED`)

Both connection-class codes are cleared the same way — a re-install, once:

Open Settings → Integrations and check the provider row. A connected: false row = CRM_CONNECTION_MISSING; a connected: true row that still misbehaves = CRM_AUTH_EXPIRED.
Re-run the OAuth install for the provider — the owner’s new consent mints a fresh token and the code clears on the next sync. Owner/admin role required — only an admin can re-authenticate an integration’s token.
Confirm the status endpoint reads connected: true and a follow-up sync completes before rejecting the next failed item as done.

Do not loop the reconnect — one re-install clears both codes. If the third install still fails, treat it as CRM_DISPATCH_FAILED and escalate with the request id (see below).

Dispatch failures (`CRM_DISPATCH_FAILED`)

The queued item could not dispatch because the CRM endpoint rejected or timed out:

Read the underlying provider response — the log line for the failed dispatch carries the raw transport detail (HTTP status, Nango/proxy response). Identify whether it was a 4xx (a validation rejection, a rate limit, a missing field) or a 5xx/timeout (transport).
Fix the cause at the provider — the permission, the field map, the rate budget — and let the queue retry. Do not overwrite the queued log item blind: an undecoded 422 will be re-stamped the same way on every re-queue.

The item you see as CRM_DISPATCH_FAILED in the run view holds the failed-at timestamp and the run id — include both when you escalate so the log line can be located.

What NOT to do

Do not retry a re-auth loop. Re-running the OAuth install on a timer just burns the provider’s consent rate limit and does not cure a dispatch-level failure. One re-install attempt, then escalate with the log line.
Do not overwrite queued log items without decoding the CRM response. Re-queueing or editing around a dispatch failure before you’ve read the underlying 4xx/5xx re-stamps the same failure — the queue redrives against the same rejection.
Do not treat CRM_CONNECTION_MISSING as a dispatch bug. A missing connection never recovers by retrying; re-install the integration once and the code clears.

Example payloads

CRM_CONNECTION_MISSING — agent tool result, missing connection:

{
  "ok": false,
  "error": "CRM_CONNECTION_MISSING",
  "message": "No active hubspot connection for this tenant. Ask the operator to reconnect via Integrations.",
  "provider": "hubspot",
  "action": "create_contact",
  "response": null,
  "duration_ms": 0
}

CRM_AUTH_EXPIRED — agent tool result, expired/revoked token:

{
  "ok": false,
  "error": "CRM_AUTH_EXPIRED",
  "message": "The hubspot connection credentials are expired or unauthorized. Ask the operator to reconnect via Integrations.",
  "provider": "hubspot",
  "action": "create_contact",
  "response": null,
  "duration_ms": 0
}

CRM_DISPATCH_FAILED — agent tool result, provider rejected the dispatch:

{
  "ok": false,
  "error": "CRM_DISPATCH_FAILED",
  "message": "The hubspot action 'create_contact' failed. Try again later or escalate to a human operator.",
  "provider": "hubspot",
  "action": "create_contact",
  "response": null,
  "duration_ms": 812
}

The companion status endpoint for the connection itself answers with the connected envelope — a connected: false body is the reconnect prompt, not an error:

{
  "data": {
    "connected": false,
    "syncs": []
  }
}

Escalation

Bring the full failed payload plus the request id from meta.request_id on the failed envelope, the provider name, and the action slug to support@devotel.io. Say which leg failed (agent tool, inbound resolution, CDP segment sync, or queued activity item) — the log line that decodes the raw transport is found by that surface and id.

Connect HubSpot & Salesforce end to end — the full sync walkthrough these codes surface on.
Error codes reference — retry classes for every code.
Troubleshooting hub — runbooks by surface.

​Troubleshooting: CRM integration sync error codes

​Symptom

​Locate the failing leg

​Owner actions by code

​Reconnecting (CRM_CONNECTION_MISSING / CRM_AUTH_EXPIRED)

​Dispatch failures (CRM_DISPATCH_FAILED)

​What NOT to do

​Example payloads

​Escalation

​Related reading

Troubleshooting: CRM integration sync error codes

Symptom

Locate the failing leg

Owner actions by code

Reconnecting (`CRM_CONNECTION_MISSING` / `CRM_AUTH_EXPIRED`)

Dispatch failures (`CRM_DISPATCH_FAILED`)

What NOT to do

Example payloads

Escalation

Related reading