Skip to content
Desktop Accounting API

Request diagnosis

View as Markdown

We cannot see your customer’s screen. We can see when the QuickBooks Web Connector checks in, whether QuickBooks answers it, what errors the Web Connector reports, which company file is open and what is ahead in the queue. From those signals the API ranks the probable causes whenever a request is waiting, runs long, times out or expires.

Where the diagnosis appears

Section titled “Where the diagnosis appears”
"diagnosis": {
  "at": "2026-10-05T15:09:05.270Z",
  "summary": "QuickBooks Desktop probably has a dialog window open.",
  "connector": {
    "lastSeenAt": "2026-10-05T15:09:03.112Z",
    "lastCheckInAt": "2026-10-05T15:09:03.112Z",
    "checkInIntervalSeconds": 3,
    "silentForSeconds": 2,
    "sessionOpen": true,
    "sessionOpenedAt": "2026-10-05T15:08:00.441Z",
    "quickbooksAnswered": false,
    "silentSessions": 1,
    "lastConnectionErrorCode": null
  },
  "probableCauses": [
    {
      "code": "quickbooks_modal_dialog",
      "likelihood": "high",
      "summary": "QuickBooks Desktop probably has a dialog window open.",
      "explanation": "...",
      "fixes": [{ "actor": "end_user", "action": "..." }],
      "details": { "silentSessions": 1, "unansweredForMs": 65000 },
      "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#quickbooks_modal_dialog"
    }
  ]
}

connector shows what we observed: the last check-in, how often the Web Connector checks in, whether a QuickBooks session is open and whether QuickBooks answered it. probableCauses lists causes from most to least likely, each with likelihood (high, medium or low), fixes addressed to you or your end user, and a link to its section below. Show the first cause’s end-user fixes to your customer, and keep the rest for your support team.

Cause codes can be added over time. Fall back to summary for codes you do not recognize.

Probable causes

Section titled “Probable causes”

This list is generated from the same cause catalog the API uses.

quickbooks_modal_dialog

QuickBooks Desktop probably has a dialog window open.

The Web Connector checked in and started a session, but QuickBooks never answered it. The Web Connector reports an open dialog (QBWC1053) only in its own window and keeps retrying about once a minute, so the server sees check-ins followed by silence.

What we observed. A session opened by authenticate gets no sendRequestXML (no company snapshot) within the silent-session window, and the Web Connector re-authenticates roughly every 60 seconds.

  • End user: On the computer that runs QuickBooks, close any open QuickBooks dialog (backup reminder, update prompt, login or "Do you want to save" window).
  • You (developer): Keep the request queued (async) or retry with the same Idempotency-Key after the end user confirms.

web_connector_registration_lost

The company file may have lost its Web Connector registration (restored from an older backup).

The Web Connector keeps a lock record inside the company file. Restoring a backup made before this application was added removes it; the Web Connector then fails locally (QBWC1079, status 3120 for AppLock) after checking in, which looks like silence to the server.

What we observed. Same as a modal dialog: sessions start and QuickBooks never answers. Ask the end user whether the company file was restored recently.

  • End user: In the Web Connector, remove this application and add it again with the same QWC file (or create a new setup link), then enter the password again.
  • You (developer): Create a new auth session if the end user no longer has the QWC file.

quickbooks_starting

QuickBooks Desktop is starting or opening the company file.

The Web Connector started a session and QuickBooks has not answered yet. Opening a large company file or starting QuickBooks without a user can take a minute or more.

What we observed. A session opened recently and QuickBooks has not answered yet; no earlier silent sessions.

  • You (developer): Wait and poll the request; it is sent as soon as QuickBooks answers.
  • End user: Keep QuickBooks open with the company file loaded to avoid start-up delays.

other_web_connector_app

Another Web Connector application may be running an update.

The Web Connector runs one application at a time. Another vendor's long update ("Another update is in progress") delays our session.

What we observed. Check-ins are late or a session waits for QuickBooks while other applications are registered in the Web Connector.

  • End user: Open the Web Connector and check whether another application is updating; let it finish.

web_connector_closed

The QuickBooks Web Connector is not running.

The Web Connector stopped checking in after a regular polling pattern. It is closed, was not started after a sign-in, or Auto-Run is unchecked for this application.

What we observed. No authenticate call within the offline threshold after regular check-ins.

  • End user: Start the QuickBooks Web Connector on the computer that runs QuickBooks and make sure Auto-Run is checked for this application.
  • You (developer): Use async requests (Prefer: respond-async) so work waits for the connection instead of failing.

computer_offline

The computer that runs QuickBooks is probably off, asleep or offline.

Nothing from the Web Connector has arrived for a long time. A computer that sleeps, restarts or loses its network stops all check-ins.

What we observed. No authenticate call for a long period (more than about 30 minutes).

  • End user: Turn on or wake the computer that runs QuickBooks, sign in to Windows and check its internet connection. Disable sleep if it must be reachable at all times.

web_connector_schedule_changed

The Web Connector is set to check in only every few minutes.

The interval between check-ins rose above 60 seconds, which happens when someone sets the "Every Min" column for this application.

What we observed. Three consecutive check-in intervals above 60 seconds.

  • End user: In the Web Connector, clear the "Every Min" value for this application (or remove and add it again) so it checks in in real time.

quickbooks_closed_no_unattended_access

QuickBooks is closed and this application may not open it.

QuickBooks reported that it could not be started for the Web Connector, or that access was not granted. When the application was authorized without "allow access even if QuickBooks is not running", QuickBooks must stay open.

What we observed. The Web Connector reported connectionError with 0x8004041D, 0x80040420, 0x80040408 or a similar HRESULT.

  • End user: Open QuickBooks with the company file, or in QuickBooks go to Edit > Preferences > Integrated Applications and allow this application to log in automatically.

quickbooks_unavailable

QuickBooks reported an error when the Web Connector tried to open it.

The Web Connector reached QuickBooks, which refused the connection. The connection error code says why.

What we observed. connectionError HRESULTs from the Web Connector in recent sessions.

  • You (developer): Look up the error code in details (or the connection statusReason) in the error reference and follow its fixes.

wrong_company_file

A different company file is open in QuickBooks.

QuickBooks answered with a company file whose identity differs from the one this connection was set up with, so nothing was sent.

What we observed. The Host/Company snapshot of the session reports a different company identity.

  • End user: Open the company file this connection was set up with.
  • You (developer): If the company was renamed on purpose, reset the company file (POST /v1/end-users/{id}/reset-company-file) after confirming with the end user.

write_recovery_pending

A write is waiting for an earlier write with an unknown outcome.

An earlier write reached QuickBooks without a confirmed result. Later writes wait so they cannot overwrite QuickBooks' recovery state. Reads continue.

What we observed. The connection holds a write barrier.

  • You (developer): Check the earlier request (details.barrierRequestId); the barrier lifts when its session ends or recovery resolves it.

behind_other_requests

The request is waiting behind other requests.

QuickBooks processes one request at a time per company file. Earlier requests on this connection run first.

What we observed. Requests ahead in the connection queue.

  • You (developer): Spread bulk work over time, use async requests, or narrow large reads.

quickbooks_processing

QuickBooks is still processing the request.

The request was handed to QuickBooks and the session is still active. Large reports and long lists can take minutes.

What we observed. The request is sent and its session made a SOAP call recently.

  • You (developer): Poll GET /v1/requests/{id}?waitSeconds=60. Do not resend.

session_interrupted

The Web Connector stopped responding while QuickBooks had the request.

The request was sent, then the session went silent. The computer may have gone to sleep or the Web Connector was closed mid-request.

What we observed. The request is sent and its session made no SOAP call for longer than the offline threshold.

  • End user: Check that the computer running QuickBooks is awake and the Web Connector is open.
  • You (developer): Wait for the request to finish or to become outcome_unknown; never resend a write before checking it.

same_connector_two_computers

The same connector file is installed on two computers.

Two computers check in with the same Web Connector username, for example two workstations of a multi-user company file. Only one may work at a time: the other is told to wait while a session is open, so requests take longer and updates alternate between the computers.

What we observed. A check-in from a second computer (different network address) for the same connector while the first computer had a live session.

  • End user: Keep the connector in the Web Connector of one computer only, the one that stays on with QuickBooks open. Remove it from the other computer's Web Connector.
  • You (developer): If both computers must stay connected, create a separate end user (and setup link) for each.

awaiting_check_in

The request is waiting for the next Web Connector check-in.

The Web Connector checks in every few seconds; the request is sent at the next check-in.

What we observed. The connector checks in regularly and nothing else blocks the request.

  • You (developer): No action needed; allow for the check-in interval in your timeout.