Error codes

Every unsupported case returns a QBO-style Fault instead of a silent difference, so you can branch on a stable code instead of parsing prose:

{
  "Fault": {
    "Error": [{
      "code": "UNSUPPORTED_BY_DESKTOP",
      "Message": "Unsupported by QuickBooks Desktop",
      "Detail": "Sparse update of Line is not supported yet; line-level and memo/tax updates land in a later TenkeyBridge release. Re-create the transaction or update header fields only.",
      "element": "Bill.Line"
    }],
    "type": "ValidationFault"
  },
  "time": "2026-07-02T00:00:00.000Z"
}

Fault.Error is always an array (currently always length 1), code is the value to branch on, and element (when present) names the field that triggered the fault.

These five codes are TenkeyBridge's own codes, part of the public API surface, and versioned as ERROR_CODES_VERSION = "2026-07" — their meaning won't change under you between versions.

Code	When you'll see it	What to do
UNSUPPORTED_BY_DESKTOP	You send or query a field, line type, item type, or operation that has no Desktop equivalent (inventory assemblies, average-cost items, unsupported line DetailTypes, Item create/update).	Remove or replace the value. The compatibility page lists exactly which fields and operations trigger this, per entity.
UNSUPPORTED_QUERY	Your query uses a clause TenkeyBridge doesn't translate reliably — multi-condition AND/OR, any ORDER BY, aggregate selects like COUNT, or STARTPOSITION beyond the first page.	Simplify to a single indexed filter (Id, a date range on TxnDate or MetaData.LastUpdatedTime, DocNumber, Active) and filter or sort the rest client-side.
UNMAPPED_ACCOUNT_TYPE	Reserved — fires when the Account entity ships (upcoming release). Documented now because error codes are versioned public API.	Not yet reachable. Once Account ships, use the closest supported type named in the fault's Detail, or check the account type mapping in COMPATIBILITY.md.
MISSING_REQUIRED_DESKTOP_ITEM	You reference something Desktop models as an item but that item doesn't exist in the company file yet — most commonly a bare-percentage or amount-off discount with no ItemRef.	Create the item in the Desktop company file, then reference it (e.g. DiscountLineDetail.ItemRef).
UNMAPPED_FIELD	You send a field TenkeyBridge has no Desktop mapping for.	Drop the field from your payload; check the entity's field table on the compatibility page for what's supported.

Numeric codes

Numeric codes carry the same meaning they have in the QuickBooks Online API, so existing QBO error-handling logic keeps working unchanged. They come from three different places: some are mapped from QuickBooks Desktop status codes when Desktop itself rejects the request (610, 5010, 6240, 2500); others are raised by TenkeyBridge's own validation before the request ever reaches Desktop (2010, 2020); and 500 signals an internal TenkeyBridge failure rather than a Desktop or validation error — report it.

Code	Meaning	Source
610	Object not found.	Mapped from Desktop status code.
5010	Stale object — an optimistic-concurrency conflict on SyncToken (Desktop's EditSequence). Re-fetch and retry.	Mapped from Desktop status code.
6240	Duplicate name exists.	Mapped from Desktop status code.
2500	Invalid reference ID.	Mapped from Desktop status code.
2010	Invalid field value.	Raised by TenkeyBridge validation before the request reaches Desktop.
2020	Required parameter missing.	Raised by TenkeyBridge validation, or mapped from Desktop status 3070 (required field missing).
500	System failure (SystemFault, HTTP 500) — an internal TenkeyBridge integrity error, not a Desktop or validation error. Report it.	Internal TenkeyBridge failure.

Any Desktop status code without a known mapping falls back to a generic ValidationFault carrying Desktop's original numeric status code, so no error is ever swallowed.