Monitor and troubleshoot
Common sync errors
What the usual failures mean, which end to fix them at, and how to re-run without making it worse.
Most integration errors are one of about a dozen things. This is that list, with the cause and the end you fix it at. The instinct to fix data here in the Cockpit is usually the wrong one: a value corrected here and not at the source stays corrected until the next run.
Connection and authentication
| Message | Cause | Fix |
|---|---|---|
| 401 / 403 | Credential rotated, expired, or the technical account was disabled | Renew the credential on the connection. Ask the other side to exclude technical accounts from password rotation |
| Connection refused / timeout | Their system is down, in maintenance, or your addresses are not allow-listed | Confirm their maintenance window, then the firewall |
| TLS / certificate error | Expired certificate, or an internal CA not trusted here | Their side renews; for an internal CA, the certificate has to be supplied |
| HTML received where JSON expected | A login or error page returned with HTTP 200 | Their side. Do not parse it; treat any HTML body as a failed run |
Identity and matching
| Symptom | Cause | Fix |
|---|---|---|
| Everything creates, nothing updates | Identifier format differs — leading zeros, a prefix, or case | Normalise in the mapping. Then merge or remove the duplicates already created |
| Zero updates on a re-import | Same cause | Same fix |
| Duplicate products with near-identical SKUs | Two sources issuing keys, or a mid-project format change | Decide the single issuer, then merge. If the duplicates already carry order history this is a careful manual job |
| Orders rejected by the ERP: unknown customer | The organisation here has no ERP customer number, or a stale one | Fix the customer master mapping. Until then those orders sit and wait |
Duplicates created by a mismatched identifier are the most expensive error on
this page. They are cheap to fix in the first hour and expensive after a week,
because by then some of them have been ordered, priced and referenced. Stop a run
that reports unexpected creates rather than letting it finish.
Data and validation
| Message | Cause | Fix |
|---|---|---|
| Unknown attribute | Column mapped to a label instead of an attribute code | Use the code |
| Invalid option | Source value has no matching option, V4A versus 1.4571 | Add the option, or map the variants to one code |
| Validation failed | The value breaks a rule on the attribute | Fix at the source, or relax a rule that is wrong |
| Unknown record | A reference value (manufacturer, material) does not exist yet | Load reference data before products. Order matters, see Import products in bulk |
| Missing required | A required attribute is empty in the source | Fill it upstream, or reconsider whether it is required for that channel |
| Number out of range / wrong by 1000 | Decimal separator read as a thousands separator | Set the source locale explicitly in the mapping |
| Garbled umlauts | Encoding mismatch, usually ISO-8859-1 read as UTF-8 | Set the encoding on the connection and re-run. Do not correct the text by hand |
Volume and timing
| Symptom | Cause | Fix |
|---|---|---|
| Run succeeded, zero records | Empty export, wrong path, or the source ran late | Check the source file first. Alert on empty results so this is never discovered by a buyer |
| Runtime growing every week | Full loads on a growing catalog, or an unfiltered query | Move to deltas with a weekly full load, or narrow the selection |
| Nightly run overruns into the morning | It starts too late, or the source's own job moved | Move the schedule, not the timeout |
| Rate limited | Too many calls, usually from live lookups on a category page | Cache, batch the calls, or reduce what is fetched live |
Outbound and webhooks
| Symptom | Cause | Fix |
|---|---|---|
| Repeated 5xx on a webhook | Receiver is failing or too slow | Their side. Confirm they acknowledge before processing |
| Duplicate orders in the ERP | Retry after a timeout, and the receiver does not deduplicate | Deduplicate on the message ID. Until then, every timeout needs a manual check |
| Events in the failed queue | Retries exhausted while the receiver was down | Fix the receiver, then replay deliberately; check first what the reconciliation run already caught |
Punchout
| Symptom | Cause |
|---|---|
| Buyer lands on a login screen | Credentials wrong, or the session did not resolve to a customer |
| Buyer sees the wrong assortment | Channel visibility left open, or the wrong channel linked to the connection |
| Buyer sees list prices | The customer's conditions are not resolving for that channel |
| Cart transfer fails or lines are dropped | Missing unit of measure, missing manufacturer part number, or a description over their length limit |
| Cart transfers but no order ever arrives | Order transmission was never configured; it is a separate message from the punchout |
How to re-run safely
- Fix the source, not the record. A value corrected here stays corrected until the next run.
- Re-run the same scope, restricted. Fifty records, then the rest.
- Expect zero creates. If a re-run creates records, the identifier is still wrong. Stop.
- Check one record by hand before you widen it.
- Write down what it was. The same feed breaks the same way in eighteen months, and the person on duty will not be you.
Next
- Monitor your syncs: catching these earlier.
- Deciding your system of record: the fix for the errors that keep coming back.