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 |
|---|---|
| Entry is refused, or the buyer lands on a login screen | Credentials wrong, or the buyer did not resolve to a contact; the reason is under Procurement › Punchout › Refused entries |
| Buyer sees the wrong assortment | Channel visibility left open, or the wrong channel linked to the punchout account |
| 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 | The punchout ends with the hand-back. The customer's system decides whether the cart becomes an order, and that order reaches you by the route you agreed with them, not through the punchout. Check Transfers for what their system received |
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.