Skip to main content
Catalog syncs and sales are processed asynchronously (see Tracking Results) — when one fails, the failure carries a human-readable reason. This page explains how to read that reason and what to do about it.

​
Where to find the reason

An item or sale that’s FAILED always has a reason recorded against it — you shouldn’t need to guess.

​
Two kinds of failure

Every failure reason falls into one of two categories, and telling them apart is the first troubleshooting step:

KRA / backend rejected it

The request reached KRA (or was validated before reaching it) and was refused because of something in your data — a code that isn’t on KRA’s accepted list, a missing classification, insufficient stock. Fix the data, then retry.

It never went through

A network or system issue on the way to KRA — a timeout, a gateway error, a dropped connection. Nothing about your request was wrong. Just retry — Sync2Books tracks the sequencing internally, so retrying never creates duplicates.
How to tell which one you’re looking at: a rejection describes a specific problem with a specific value — often naming the field and, for code-list fields, the exact accepted values. A system-level failure reads like an infrastructure error (timeout, gateway, connection) and, where Sync2Books can identify it as such, is prefixed retryable:.
A retryable:-prefixed message is a promise, not just a hint: Sync2Books’ internal sequence numbers (itemCd, invcNo, and similar) are held in place for these failures specifically so a retry is always safe. You will never be told to fix your data for one of these — just try again.

​
Common failure reasons

This table grows as new failure reasons are confirmed. If you hit one that isn’t listed here and can’t tell which category it falls into from the message alone, contact support with the exact reason text.

​
Retrying

  • Catalog items: POST …/catalog/items/sync with force: true, or onlyPending: true to only retry items that aren’t yet REGISTERED (the default).
  • Sales: resubmit the same sale — Sync2Books’ internal idempotency means a retried sale is never double-submitted to KRA.
Retrying a data rejection without fixing the underlying value will simply fail again with the same reason.