QuickBooks Desktop errors don't have to be cryptic

Ask anyone who has integrated QuickBooks Desktop about error handling and you'll get the same story: numeric status codes, COM HRESULTs, and messages that describe the symptom but not the cause — sometimes not even the symptom.

We made two decisions early that shaped TenkeyBridge's whole error surface.

1. Desktop faults become QBO faults

Your code already handles QBO's Fault.Error[] shape — type, code, message, element. So every Desktop status code, session error, and connection failure is translated into that exact shape, with the original Desktop detail preserved. One error format, and it's the one you've already written handlers for.

2. Every fault explains itself

Each error also carries a tkb block: causes in plain English, fixes you can actually take, and a docsUrl deep-linking the compatibility page for that entity. The 3140 "invalid reference" you'd normally spend an afternoon on arrives saying which reference, why Desktop rejected it, and what to send instead.

The honesty rule

The part we're most opinionated about: when a QBO field can't be represented in Desktop, TenkeyBridge fails loud with a 422 and a documented reason. Silently dropping fields ships corrupted expectations to production. The compatibility page is the contract — what maps, what doesn't, and what happens when it doesn't.