# Request diagnosis Source: https://www.desktopaccountingapi.com/docs/troubleshooting/ > How the API explains why a request is waiting, slow, timed out or expired, and every probable cause it can report with its fixes. 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 - `diagnosis` on the request resource (`GET /v1/requests/{id}`) while the request waits or runs, and after it timed out or expired. - `details.diagnosis` on the errors [`REQUEST_TIMEOUT_NOT_SENT`](https://www.desktopaccountingapi.com/docs/errors/#request_timeout_not_sent), [`REQUEST_EXPIRED`](https://www.desktopaccountingapi.com/docs/errors/#request_expired), [`QBD_QUICKBOOKS_NOT_RESPONDING`](https://www.desktopaccountingapi.com/docs/errors/#qbd_quickbooks_not_responding) and [`QBD_REQUEST_TIMEOUT`](https://www.desktopaccountingapi.com/docs/errors/#qbd_request_timeout). - The `diagnosed` step in the request timeline, and the request detail page in the dashboard. - Webhook payloads for request events, which carry the request's `diagnosis`. ```json "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 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.