Troubleshooting

Before you start

All behaviour in these guides is validated against the QuickBooks Web Connector simulator and not yet against a real QuickBooks Desktop install. The acceptance run on a Windows rig is a launch step. Real installs can differ in small ways, so report anything that does not match.

Request stays queued or returns 202

QuickBooks Desktop cannot be reached from the internet. The Web Connector on the customer's PC polls us, so a request waits until the next poll. If it has not finished within the wait, the API returns 202 with a request id (the SDKs call this request_pending when you list). Poll GET /v1/requests/{id}, or use requests.wait in the SDKs.

If it stays queued, check that the PC is on, QuickBooks is open or the Web Connector entry is set to Auto-Run, and the file shows Connected in the dashboard.

File shows Asleep

A file is Asleep when the Web Connector has not polled for 2 hours. The PC may be off or asleep, or the Web Connector may be closed. Requests queue and run when it polls again, and the file returns to Connected by itself.

File shows Broken

A file is Broken after 72 hours without a poll, or on a connection error reported by the Web Connector. We email once per incident and send a company_file.broken webhook. Fix the cause on the PC, then use Send reconnect link in the dashboard or create a new connect link, and the file recovers on the next poll.

QuickBooks must be open or on Auto-Run

The Web Connector can start QuickBooks only when the entry is set to Auto-Run and the user is signed in to Windows. Otherwise open QuickBooks with the company file yourself. If QuickBooks is closed and cannot be started you get quickbooks_could_not_start (HRESULT 0x80040408).

Single user mode and dialogs

A file open in single user mode by another person, or a dialog waiting for an answer in QuickBooks (a license prompt, an update or an unsaved window), blocks the Web Connector. Close the dialog, or return the file to multi user mode, and the queued request continues.

Writes: outcome_unknown

If a write was sent and no answer came back, the request ends as outcome_unknown (502). It may or may not have been applied. Never blindly retry it. Query the object by RefNumber (for example GET /v1/qbd/invoices?refNumber=1042). If it exists, the write worked. If not, write again with a new Idempotency-Key.

Wrong password in the Web Connector

The Web Connector password is derived from a server secret. If the secret changes (for example BETTER_AUTH_SECRET is rotated on a self-run deployment), every .qwc file stops working with an authentication failure. Send each customer a reconnect link so they download a new file and enter the new password.

QuickBooks status codes and connection errors

Each line is one code from the error catalogue: the code, the HTTP status we return, whether a retry can help, the title and the guide page.

code                        http  retryable  title                                                  guide
duplicate_name              409   no         QuickBooks status 3100: name already in use            /errors/3100
invalid_reference           422   no         QuickBooks status 3140: invalid reference              /errors/3140
revision_conflict           409   no         QuickBooks status 3200: revisionNumber out of date     /errors/3200
edition_not_supported       422   no         QuickBooks status 3250: not supported by this edition  /errors/3250
quickbooks_error            502   no         QuickBooks returned an error                           /errors/quickbooks-error
invalid_response            502   yes        Unreadable QuickBooks reply                            /errors/invalid-response
quickbooks_could_not_start  502   yes        HRESULT 0x80040408: QuickBooks could not be started    /errors/qb-could-not-start
connection_error            502   yes        Web Connector reported an error                        /errors/connection-error
outcome_unknown             502   no         Outcome unknown                                        /errors/outcome-unknown