Every error response has the same shape, and every code below is stable: its meaning never changes, and new codes only get added. The docsUrl field in an error body links straight to the matching section on this page.
{
"error": {
"type": "INTEGRATION_CONNECTION_ERROR",
"code": "QBD_MODAL_DIALOG_OPEN",
"message": "QuickBooks Desktop has a dialog window open, so it could not accept the request.",
"userFacingMessage": "QuickBooks Desktop has a window open that needs attention. Close any open QuickBooks dialog on the computer that runs QuickBooks, then try again.",
"httpStatusCode": 503,
"integrationCode": "0x80040414",
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "A modal dialog blocks every integrated application until someone closes it.",
"fixes": [{ "actor": "end_user", "action": "Close the open dialog in QuickBooks Desktop on the host computer." }],
Read Error handling for what each field means and how to route errors in your code. The short version:
Branch on code, not on message. Messages can get more specific over time.
Show userFacingMessage to your customer. It never contains keys, billing details or internal identifiers.
Retry only when retryable is true (also sent as the Daapi-Should-Retry header). Never resend a write whose outcome is unknown or pending.
Quote requestId when you contact support. The dashboard request log opens it directly.
This page is generated from the same error catalog the API uses at runtime, so it always matches the codes the API sends. The catalog is also published as JSON at /docs/errors.json, with every code, retry rule, cause, fix, documented details key, the qbXML status mapping and the diagnosis causes, for tools and SDKs.
Retry the same request (retry_same_request). Repeating the identical request (same Idempotency-Key for writes) can succeed. SDKs retry it automatically with backoff.
Read the request instead of resending (poll_request). The request keeps running. Poll GET /v1/requests/{id}?waitSeconds=60; never resend it.
Never resend; check QuickBooks first (never_resend_check_first). Never resend automatically. Check in QuickBooks whether the change exists before trying again.
Change the request or the setup first (change_request_or_environment). Repeating the same request fails the same way. Change the request, or have the end user or developer apply a fix first.
Invalid request error INVALID_REQUEST_ERROR
The request is invalid. Fix it before sending it again.
INVALID_JSON
HTTP status
400
Retry
Change the request or the setup first
Outcome
not_applied
Message.The request body is not valid JSON.
Cause.The body could not be parsed as JSON, or the Content-Type header does not match the body.
What the end user sees. The application sent a request QuickBooks could not accept. Please contact the application provider.
How to fix it
You (developer):Send a UTF-8 JSON body with Content-Type: application/json.
Example response body
{
"error": {
"type": "INVALID_REQUEST_ERROR",
"code": "INVALID_JSON",
"message": "The request body is not valid JSON.",
"userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.",
"httpStatusCode": 400,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "The body could not be parsed as JSON, or the Content-Type header does not match the body.",
"fixes": [
{
"actor": "developer",
"action": "Send a UTF-8 JSON body with Content-Type: application/json."
Message.A text value contains a character QuickBooks cannot store.
Cause.US editions of QuickBooks Desktop store text in the Windows-1252 code page. Characters outside it (emoji, Greek or Asian scripts, fullwidth forms such as ＆, control characters) are rejected rather than silently changed. Accented Latin letters, €, µ, the no-break space, curly quotes and dashes are stored as sent; decomposed accents are normalized to their composed form first.
What the end user sees. The application sent a request QuickBooks could not accept. Please contact the application provider.
How to fix it
You (developer):Replace the character reported in details in the field named in param; details.suggestion names a replacement when there is an obvious one.
Details
details.codePoint: Unicode code point of the first rejected character.
details.character: The character itself, or null for control characters.
details.index: Its position in the value (0-based, in characters).
details.suggestion: A replacement QuickBooks can store, or null.
"message": "A text value contains a character QuickBooks cannot store.",
"userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.",
"httpStatusCode": 400,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "US editions of QuickBooks Desktop store text in the Windows-1252 code page. Characters outside it (emoji, Greek or Asian scripts, fullwidth forms such as ＆, control characters) are rejected rather than silently changed. Accented Latin letters, €, µ, the no-break space, curly quotes and dashes are stored as sent; decomposed accents are normalized to their composed form first.",
"fixes": [
{
"actor": "developer",
"action": "Replace the character reported in `details` in the field named in `param`; `details.suggestion` names a replacement when there is an obvious one."
Message.The cursor is malformed, out of date or belongs to another end user.
Cause.Only the most recent cursor of a list can be used, and only for the end user and query that produced it. Every page returns a new cursor; resending one repeats its page at most twice.
What the end user sees. The application sent a request QuickBooks could not accept. Please contact the application provider.
How to fix it
You (developer):Use the nextCursor from the latest page, or start the list again without a cursor.
"message": "The cursor is malformed, out of date or belongs to another end user.",
"userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.",
"httpStatusCode": 400,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "Only the most recent cursor of a list can be used, and only for the end user and query that produced it. Every page returns a new cursor; resending one repeats its page at most twice.",
"fixes": [
{
"actor": "developer",
"action": "Use the nextCursor from the latest page, or start the list again without a cursor."
Message.Filter parameters cannot change while paging with a cursor.
Cause.Filters are fixed when a list starts and the cursor remembers them. A continue request may resend exactly the same filters; a changed, added or dropped filter would describe a different list.
What the end user sees. The application sent a request QuickBooks could not accept. Please contact the application provider.
How to fix it
You (developer):Send cursor (and optionally limit) alone, or with exactly the filters of the first request. To change a filter, start the list again without a cursor.
"message": "Filter parameters cannot change while paging with a cursor.",
"userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.",
"httpStatusCode": 400,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "Filters are fixed when a list starts and the cursor remembers them. A continue request may resend exactly the same filters; a changed, added or dropped filter would describe a different list.",
"fixes": [
{
"actor": "developer",
"action": "Send cursor (and optionally limit) alone, or with exactly the filters of the first request. To change a filter, start the list again without a cursor."
Message.The connected QuickBooks version does not support this field or operation.
Cause.The field or operation was introduced in a newer qbXML version than the connected QuickBooks supports. details.minimumQbxmlVersion gives the version needed.
What the end user sees. This feature needs a newer version of QuickBooks Desktop. Please contact the application provider.
How to fix it
You (developer):Omit the field for this end user, or check the connection's qbxmlVersion before sending it.
End user:Update QuickBooks Desktop to a release that supports the feature.
Details
details.minimumQbxmlVersion: qbXML version that introduced the field or operation.
details.qbxmlVersion: qbXML version of the connected QuickBooks.
"message": "The connected QuickBooks version does not support this field or operation.",
"userFacingMessage": "This feature needs a newer version of QuickBooks Desktop. Please contact the application provider.",
"httpStatusCode": 422,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "The field or operation was introduced in a newer qbXML version than the connected QuickBooks supports. `details.minimumQbxmlVersion` gives the version needed.",
"fixes": [
{
"actor": "developer",
"action": "Omit the field for this end user, or check the connection's qbxmlVersion before sending it."
},
{
"actor": "end_user",
"action": "Update QuickBooks Desktop to a release that supports the feature."
Message.QuickBooks Desktop offers no way to perform this operation through its integration interface.
Cause.This is a documented incompatibility: the QuickBooks Desktop SDK (qbXML) has no request for this operation, so no integration can perform it. details.alternatives lists what to do instead.
What the end user sees. This action is not available for QuickBooks Desktop. Please contact the application provider.
How to fix it
You (developer):Use one of the alternatives in details.alternatives, for example deleting the transaction instead of voiding it.
End user:Perform the action in the QuickBooks Desktop window.
"message": "QuickBooks Desktop offers no way to perform this operation through its integration interface.",
"userFacingMessage": "This action is not available for QuickBooks Desktop. Please contact the application provider.",
"httpStatusCode": 422,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "This is a documented incompatibility: the QuickBooks Desktop SDK (qbXML) has no request for this operation, so no integration can perform it. `details.alternatives` lists what to do instead.",
"fixes": [
{
"actor": "developer",
"action": "Use one of the alternatives in details.alternatives, for example deleting the transaction instead of voiding it."
},
{
"actor": "end_user",
"action": "Perform the action in the QuickBooks Desktop window."
Message.Test projects in this organization already connect the maximum number of company files.
Cause.Test projects are free and limited to a small number of connected company files per organization. Reconnecting an end user to the same company file does not count again. A company file keeps counting for 30 days after a test connection last used it, also after its end user is deleted or its company file is reset. The connection checks the limit again whenever a test connection adopts a company file.
What the end user sees. This application cannot connect another QuickBooks company file right now. Please contact the application provider.
How to fix it
You (developer):Connect the company file in a production project, or reuse a company file your test projects already connect. Files you stopped using free their slot 30 days after their last use.
Support:Ask support to raise the limit for a legitimate test setup.
Details
details.used: Company files connected across the organization test projects.
"message": "Test projects in this organization already connect the maximum number of company files.",
"userFacingMessage": "This application cannot connect another QuickBooks company file right now. Please contact the application provider.",
"httpStatusCode": 403,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "Test projects are free and limited to a small number of connected company files per organization. Reconnecting an end user to the same company file does not count again. A company file keeps counting for 30 days after a test connection last used it, also after its end user is deleted or its company file is reset. The connection checks the limit again whenever a test connection adopts a company file.",
"fixes": [
{
"actor": "developer",
"action": "Connect the company file in a production project, or reuse a company file your test projects already connect. Files you stopped using free their slot 30 days after their last use."
},
{
"actor": "support",
"action": "Ask support to raise the limit for a legitimate test setup."
Message.This secret key is read-only and cannot change data.
Cause.The request was made with a read-only secret key. Read-only keys can call GET operations and passthrough requests that contain only queries (...QueryRq). Creating, updating, deleting or voiding objects, writes through passthrough, auth sessions, end-user changes, request cancellation and webhook endpoint changes need a full-access key. The API rejects the request before anything is queued or sent to QuickBooks.
What the end user sees. This application could not connect to QuickBooks right now. Please contact the application provider.
How to fix it
You (developer):Use a full-access secret key for writes, or keep this key for read-only tools such as an MCP connection for AI agents.
Example response body
{
"error": {
"type": "PERMISSION_ERROR",
"code": "API_KEY_READ_ONLY",
"message": "This secret key is read-only and cannot change data.",
"userFacingMessage": "This application could not connect to QuickBooks right now. Please contact the application provider.",
"httpStatusCode": 403,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "The request was made with a read-only secret key. Read-only keys can call GET operations and passthrough requests that contain only queries (`...QueryRq`). Creating, updating, deleting or voiding objects, writes through passthrough, auth sessions, end-user changes, request cancellation and webhook endpoint changes need a full-access key. The API rejects the request before anything is queued or sent to QuickBooks.",
"fixes": [
{
"actor": "developer",
"action": "Use a full-access secret key for writes, or keep this key for read-only tools such as an MCP connection for AI agents."
Message.Production data requests are paused because the organization has no active subscription.
Cause.The organization's 30-day production trial ended without a subscription, or its subscription ended. Health checks, auth sessions, end users, setup and test projects keep working.
What the end user sees. This application could not connect to QuickBooks right now. Please contact the application provider.
How to fix it
You (developer):An organization owner starts a subscription on the dashboard's Billing page (details.billingUrl). Production requests work again within a minute.
"message": "Production data requests are paused because the organization has no active subscription.",
"userFacingMessage": "This application could not connect to QuickBooks right now. Please contact the application provider.",
"httpStatusCode": 402,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "The organization's 30-day production trial ended without a subscription, or its subscription ended. Health checks, auth sessions, end users, setup and test projects keep working.",
"fixes": [
{
"actor": "developer",
"action": "An organization owner starts a subscription on the dashboard's Billing page (`details.billingUrl`). Production requests work again within a minute."
Message.Production data requests are paused because payment failed.
Cause.The subscription has been past due for more than the 7-day grace period. Health checks, auth sessions, end users, setup and test projects keep working.
What the end user sees. This application could not connect to QuickBooks right now. Please contact the application provider.
How to fix it
You (developer):An organization owner updates the payment method on the dashboard's Billing page (details.billingUrl, then Manage billing). Production requests work again once the payment succeeds.
"message": "Production data requests are paused because payment failed.",
"userFacingMessage": "This application could not connect to QuickBooks right now. Please contact the application provider.",
"httpStatusCode": 402,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "The subscription has been past due for more than the 7-day grace period. Health checks, auth sessions, end users, setup and test projects keep working.",
"fixes": [
{
"actor": "developer",
"action": "An organization owner updates the payment method on the dashboard's Billing page (`details.billingUrl`, then Manage billing). Production requests work again once the payment succeeds."
Message.Too many requests for this project. Retry after the time in Retry-After.
Cause.The project exceeded its request rate across all keys, or too many requests (including ones with invalid keys) came from one IP address. details.scope says which limit applied.
What the end user sees. Something went wrong while contacting QuickBooks. Please try again in a moment.
How to fix it
You (developer):Retry after the Retry-After interval and spread requests over time. Read the RateLimit-* headers to stay under the limit.
Details
details.scope: project (requests per project across all keys) or ip (requests or failed authentications from one IP address).
"message": "Too many requests for this project. Retry after the time in Retry-After.",
"userFacingMessage": "Something went wrong while contacting QuickBooks. Please try again in a moment.",
"httpStatusCode": 429,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "The project exceeded its request rate across all keys, or too many requests (including ones with invalid keys) came from one IP address. `details.scope` says which limit applied.",
"fixes": [
{
"actor": "developer",
"action": "Retry after the Retry-After interval and spread requests over time. Read the RateLimit-* headers to stay under the limit."
Message.This connection has too many pending requests.
Cause.QuickBooks processes one request at a time per company file. The connection already has the maximum number of pending requests (200), or of callers waiting synchronously (50). details.reason says which.
What the end user sees. Something went wrong while contacting QuickBooks. Please try again in a moment.
How to fix it
You (developer):Wait for pending requests to finish before submitting more.
You (developer):Use async requests (Prefer: respond-async) for bulk work instead of many concurrent synchronous calls.
"message": "This connection has too many pending requests.",
"userFacingMessage": "Something went wrong while contacting QuickBooks. Please try again in a moment.",
"httpStatusCode": 429,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "QuickBooks processes one request at a time per company file. The connection already has the maximum number of pending requests (200), or of callers waiting synchronously (50). `details.reason` says which.",
"fixes": [
{
"actor": "developer",
"action": "Wait for pending requests to finish before submitting more."
},
{
"actor": "developer",
"action": "Use async requests (Prefer: respond-async) for bulk work instead of many concurrent synchronous calls."
Message.The QuickBooks Web Connector for this end user has not checked in recently.
Cause.The computer is off, asleep or signed out, the Web Connector is closed, or Auto-Run is off.
What the end user sees. The computer that runs QuickBooks Desktop is not reachable. Make sure it is on, signed in, and that the QuickBooks Web Connector is running.
How to fix it
End user:Turn on and sign in to the computer that runs QuickBooks, start the QuickBooks Web Connector and check Auto-Run for this application.
You (developer):Retry after the end user confirms the Web Connector is running.
"message": "The QuickBooks Web Connector for this end user has not checked in recently.",
"userFacingMessage": "The computer that runs QuickBooks Desktop is not reachable. Make sure it is on, signed in, and that the QuickBooks Web Connector is running.",
"httpStatusCode": 503,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "The computer is off, asleep or signed out, the Web Connector is closed, or Auto-Run is off.",
"fixes": [
{
"actor": "end_user",
"action": "Turn on and sign in to the computer that runs QuickBooks, start the QuickBooks Web Connector and check Auto-Run for this application."
},
{
"actor": "developer",
"action": "Retry after the end user confirms the Web Connector is running."
Message.The Web Connector could not open QuickBooks Desktop.
Cause.QuickBooks reported an error opening the connection that has no more specific mapping. integrationCode has the HRESULT.
What the end user sees. QuickBooks Desktop could not be opened on the computer that runs it. Make sure QuickBooks is installed and the company file opens normally.
How to fix it
End user:Open QuickBooks Desktop and the company file on the host computer and close any open windows.
"message": "The Web Connector could not open QuickBooks Desktop.",
"userFacingMessage": "QuickBooks Desktop could not be opened on the computer that runs it. Make sure QuickBooks is installed and the company file opens normally.",
"httpStatusCode": 503,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "QuickBooks reported an error opening the connection that has no more specific mapping. `integrationCode` has the HRESULT.",
"fixes": [
{
"actor": "end_user",
"action": "Open QuickBooks Desktop and the company file on the host computer and close any open windows."
},
{
"actor": "support",
"action": "Look up the HRESULT in integrationCode."
Message.QuickBooks Desktop could not be started on the host computer.
Cause.The Web Connector tried to start QuickBooks and failed, often because it is not installed for the signed-in Windows user or another instance is starting.
What the end user sees. QuickBooks Desktop could not start. Open QuickBooks and your company file on the computer that runs it, then try again.
How to fix it
End user:Open QuickBooks Desktop and the company file manually and leave it open.
"message": "QuickBooks Desktop could not be started on the host computer.",
"userFacingMessage": "QuickBooks Desktop could not start. Open QuickBooks and your company file on the computer that runs it, then try again.",
"httpStatusCode": 503,
"integrationCode": "0x80040408",
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "The Web Connector tried to start QuickBooks and failed, often because it is not installed for the signed-in Windows user or another instance is starting.",
"fixes": [
{
"actor": "end_user",
"action": "Open QuickBooks Desktop and the company file manually and leave it open."
Message.QuickBooks Desktop has a dialog window open, so it could not accept the request.
Cause.A modal dialog (for example a backup reminder or an update prompt) blocks every integrated application until someone closes it.
What the end user sees. QuickBooks Desktop has a window open that needs attention. Close any open QuickBooks dialog on the computer that runs QuickBooks, then try again.
How to fix it
End user:Close the open dialog in QuickBooks Desktop on the host computer.
You (developer):Retry after the end user confirms; reads can be retried automatically.
"message": "QuickBooks Desktop has a dialog window open, so it could not accept the request.",
"userFacingMessage": "QuickBooks Desktop has a window open that needs attention. Close any open QuickBooks dialog on the computer that runs QuickBooks, then try again.",
"httpStatusCode": 503,
"integrationCode": "0x80040414",
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "A modal dialog (for example a backup reminder or an update prompt) blocks every integrated application until someone closes it.",
"fixes": [
{
"actor": "end_user",
"action": "Close the open dialog in QuickBooks Desktop on the host computer."
},
{
"actor": "developer",
"action": "Retry after the end user confirms; reads can be retried automatically."
Message.The Web Connector checked in, but QuickBooks Desktop did not answer it, so the request was not sent.
Cause.The Web Connector started a session and QuickBooks never answered. Most often a QuickBooks dialog is open: the Web Connector reports that (QBWC1053) only in its own window and retries. A company file restored from an older backup can also fail this way (QBWC1079). details.diagnosis ranks the probable causes.
What the end user sees. QuickBooks Desktop is not responding. Close any open QuickBooks window or dialog on the computer that runs QuickBooks, then try again.
How to fix it
End user:On the computer that runs QuickBooks, close any open QuickBooks dialog or window (preferences, backup reminder, update prompt, login).
End user:If the company file was restored from a backup, remove this application from the Web Connector and add it again.
You (developer):Retry after the end user confirms, or use async requests so the work waits for QuickBooks.
Details
details.requestId: The request that was not sent.
details.diagnosis: Probable causes ranked by likelihood.
"message": "The Web Connector checked in, but QuickBooks Desktop did not answer it, so the request was not sent.",
"userFacingMessage": "QuickBooks Desktop is not responding. Close any open QuickBooks window or dialog on the computer that runs QuickBooks, then try again.",
"httpStatusCode": 503,
"integrationCode": "QBWC1053",
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "The Web Connector started a session and QuickBooks never answered. Most often a QuickBooks dialog is open: the Web Connector reports that (QBWC1053) only in its own window and retries. A company file restored from an older backup can also fail this way (QBWC1079). `details.diagnosis` ranks the probable causes.",
"fixes": [
{
"actor": "end_user",
"action": "On the computer that runs QuickBooks, close any open QuickBooks dialog or window (preferences, backup reminder, update prompt, login)."
},
{
"actor": "end_user",
"action": "If the company file was restored from a backup, remove this application from the Web Connector and add it again."
},
{
"actor": "developer",
"action": "Retry after the end user confirms, or use async requests so the work waits for QuickBooks."
Message.A different QuickBooks company file is open on the host computer.
Cause.QuickBooks opens one company file at a time per computer, and the open file is not the one this connection uses.
What the end user sees. A different company file is open in QuickBooks Desktop. Open the company file you connected, then try again.
How to fix it
End user:Close the open company file and open the connected one.
You (developer):Retry after the end user opens the right file. 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.
Details
details.openCompanyName: Company name QuickBooks reported for the open file (when the snapshot proved the mismatch).
details.connectedCompanyName: Company name of the file this connection was set up with.
details.channel: qbwc_connection_error when inferred from the Web Connector (it reports 0x80040408 where the QuickBooks SDK reports 0x8004040A).
details.inferred: true when the code was inferred from a Web Connector HRESULT rather than proven by the company snapshot.
"message": "A different QuickBooks company file is open on the host computer.",
"userFacingMessage": "A different company file is open in QuickBooks Desktop. Open the company file you connected, then try again.",
"httpStatusCode": 503,
"integrationCode": "0x8004040A",
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "QuickBooks opens one company file at a time per computer, and the open file is not the one this connection uses.",
"fixes": [
{
"actor": "end_user",
"action": "Close the open company file and open the connected one."
},
{
"actor": "developer",
"action": "Retry after the end user opens the right file. 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."
Message.The company file reports a different company identity than this connection.
Cause.The file looks like a copy or a different company than the one this connection was set up with.
What the end user sees. The open company file does not match the one that was connected. Please contact the application provider.
How to fix it
You (developer):Confirm with the end user which file is correct, then reset the company file (POST /v1/end-users/{id}/reset-company-file) or reconnect with a new auth session.
"message": "The company file reports a different company identity than this connection.",
"userFacingMessage": "The open company file does not match the one that was connected. Please contact the application provider.",
"httpStatusCode": 409,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "The file looks like a copy or a different company than the one this connection was set up with.",
"fixes": [
{
"actor": "developer",
"action": "Confirm with the end user which file is correct, then reset the company file (POST /v1/end-users/{id}/reset-company-file) or reconnect with a new auth session."
Message.The company file is open in a mode that does not allow this connection.
Cause.The file is open in single-user mode by another application or user, or in a different file mode than requested.
What the end user sees. QuickBooks Desktop is using the company file in a way that blocks the connection. Switch to single-user mode or close other programs using the file, then try again.
How to fix it
End user:Close other users or applications that have the file open, or switch the file mode in QuickBooks.
"message": "The company file is open in a mode that does not allow this connection.",
"userFacingMessage": "QuickBooks Desktop is using the company file in a way that blocks the connection. Switch to single-user mode or close other programs using the file, then try again.",
"httpStatusCode": 503,
"integrationCode": "0x80040410",
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "The file is open in single-user mode by another application or user, or in a different file mode than requested.",
"fixes": [
{
"actor": "end_user",
"action": "Close other users or applications that have the file open, or switch the file mode in QuickBooks."
Message.The first connection to this company file must be authorized by the QuickBooks Admin user.
Cause.QuickBooks allows only the Admin user to grant an application first access to a company file.
What the end user sees. QuickBooks needs the Admin user to allow this connection the first time. Sign in to QuickBooks as Admin, in single-user mode, and run the Web Connector again.
How to fix it
End user:Sign in to the company file as Admin in single-user mode and accept the authorization prompt.
"message": "The first connection to this company file must be authorized by the QuickBooks Admin user.",
"userFacingMessage": "QuickBooks needs the Admin user to allow this connection the first time. Sign in to QuickBooks as Admin, in single-user mode, and run the Web Connector again.",
"httpStatusCode": 503,
"integrationCode": "0x80040418",
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "QuickBooks allows only the Admin user to grant an application first access to a company file.",
"fixes": [
{
"actor": "end_user",
"action": "Sign in to the company file as Admin in single-user mode and accept the authorization prompt."
Message.QuickBooks has not granted this application access to the company file.
Cause.Access was denied at the authorization prompt, later revoked, or the application is not allowed to sign in automatically.
What the end user sees. QuickBooks Desktop has not allowed this connection. In QuickBooks, open Edit > Preferences > Integrated Applications and allow access for this application.
How to fix it
End user:In QuickBooks, open Edit > Preferences > Integrated Applications > Company Preferences and allow this application, including access when QuickBooks is not running.
"message": "QuickBooks has not granted this application access to the company file.",
"userFacingMessage": "QuickBooks Desktop has not allowed this connection. In QuickBooks, open Edit > Preferences > Integrated Applications and allow access for this application.",
"httpStatusCode": 503,
"integrationCode": "0x80040420",
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "Access was denied at the authorization prompt, later revoked, or the application is not allowed to sign in automatically.",
"fixes": [
{
"actor": "end_user",
"action": "In QuickBooks, open Edit > Preferences > Integrated Applications > Company Preferences and allow this application, including access when QuickBooks is not running."
Message.The request timed out before it was sent to QuickBooks and was canceled.
Cause.The Web Connector did not pick up the request within Daapi-Timeout-Seconds. Nothing reached QuickBooks. details.diagnosis lists the probable causes the server observed (for example a QuickBooks dialog left open, or the Web Connector not running).
What the end user sees. QuickBooks Desktop did not respond in time. Please try again.
How to fix it
You (developer):Retry with the same Idempotency-Key, or use a longer Daapi-Timeout-Seconds.
End user:Make sure the computer running QuickBooks is on and the Web Connector is running.
Details
details.requestId: The canceled request.
details.diagnosis: Probable causes ranked by likelihood, with the connector last check-in (see the request diagnosis object).
"message": "The request timed out before it was sent to QuickBooks and was canceled.",
"userFacingMessage": "QuickBooks Desktop did not respond in time. Please try again.",
"httpStatusCode": 504,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "The Web Connector did not pick up the request within Daapi-Timeout-Seconds. Nothing reached QuickBooks. `details.diagnosis` lists the probable causes the server observed (for example a QuickBooks dialog left open, or the Web Connector not running).",
"fixes": [
{
"actor": "developer",
"action": "Retry with the same Idempotency-Key, or use a longer Daapi-Timeout-Seconds."
},
{
"actor": "end_user",
"action": "Make sure the computer running QuickBooks is on and the Web Connector is running."
QuickBooks rejected the request. Developer-actionable.
QBD_REQUEST_ERROR
HTTP status
422
Retry
Change the request or the setup first
Outcome
not_applied
Message.QuickBooks Desktop rejected the request.
Cause.QuickBooks returned an error status without a more specific mapping. integrationCode holds the qbXML statusCode and details.qbxmlStatusMessage its message.
What the end user sees. The application sent a request QuickBooks could not accept. Please contact the application provider.
How to fix it
You (developer):Read details.qbxmlStatusMessage and correct the request.
"message": "QuickBooks Desktop rejected the request.",
"userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.",
"httpStatusCode": 422,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "QuickBooks returned an error status without a more specific mapping. `integrationCode` holds the qbXML statusCode and `details.qbxmlStatusMessage` its message.",
"fixes": [
{
"actor": "developer",
"action": "Read details.qbxmlStatusMessage and correct the request."
Message.The QuickBooks object is in use: open or locked in QuickBooks, or still used by other records.
Cause.Usually the record is open for editing in QuickBooks or locked by another user in multi-user mode, which clears once it is closed. A deletion can also be refused because other records still use the object (for example an account referenced by a transaction); that does not clear with time.
What the end user sees. Someone is editing this record in QuickBooks Desktop. Close it in QuickBooks, then try again.
How to fix it
End user:Close the record in QuickBooks Desktop.
You (developer):Retry after a short wait. If a deletion still fails after the record is closed, other records use it: remove or change those first, or deactivate it instead of deleting.
"message": "The QuickBooks object is in use: open or locked in QuickBooks, or still used by other records.",
"userFacingMessage": "Someone is editing this record in QuickBooks Desktop. Close it in QuickBooks, then try again.",
"httpStatusCode": 409,
"integrationCode": "3175",
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "Usually the record is open for editing in QuickBooks or locked by another user in multi-user mode, which clears once it is closed. A deletion can also be refused because other records still use the object (for example an account referenced by a transaction); that does not clear with time.",
"fixes": [
{
"actor": "end_user",
"action": "Close the record in QuickBooks Desktop."
},
{
"actor": "developer",
"action": "Retry after a short wait. If a deletion still fails after the record is closed, other records use it: remove or change those first, or deactivate it instead of deleting."
Message.The QuickBooks user or the integration lacks permission for this operation.
Cause.Status 3260: the connection signs in as the QuickBooks user chosen at authorization, and that user's role does not allow the operation. Status 3261: the integration has no permission to access personal data (for example payroll reports, Social Security numbers or credit card numbers), which the QuickBooks Admin grants in the Integrated Applications preferences.
What the end user sees. QuickBooks Desktop did not give this connection permission for this. Ask your QuickBooks Admin to update the permissions.
How to fix it
End user:For status 3260: in QuickBooks, give the integration's user the required permission, or reauthorize with a user that has it.
End user:For status 3261: signed in to QuickBooks as Admin, choose Edit > Preferences > Integrated Applications > Company Preferences, select the application, click Properties and allow it to access personal data.
You (developer):Check integrationCode, then show the end user the matching fix; nothing was changed.
"message": "The QuickBooks user or the integration lacks permission for this operation.",
"userFacingMessage": "QuickBooks Desktop did not give this connection permission for this. Ask your QuickBooks Admin to update the permissions.",
"httpStatusCode": 403,
"integrationCode": "3260",
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "Status 3260: the connection signs in as the QuickBooks user chosen at authorization, and that user's role does not allow the operation. Status 3261: the integration has no permission to access personal data (for example payroll reports, Social Security numbers or credit card numbers), which the QuickBooks Admin grants in the Integrated Applications preferences.",
"fixes": [
{
"actor": "end_user",
"action": "For status 3260: in QuickBooks, give the integration's user the required permission, or reauthorize with a user that has it."
},
{
"actor": "end_user",
"action": "For status 3261: signed in to QuickBooks as Admin, choose Edit > Preferences > Integrated Applications > Company Preferences, select the application, click Properties and allow it to access personal data."
},
{
"actor": "developer",
"action": "Check integrationCode, then show the end user the matching fix; nothing was changed."
An unexpected error on our side. outcome says whether a write may have reached QuickBooks.
QBD_RESPONSE_UNREADABLE
HTTP status
500
Retry
Change the request or the setup first
Outcome
not_applicable
Message.QuickBooks answered, but the response could not be converted to the documented JSON shape.
Cause.QuickBooks returned data that does not match the documented response schema (for example a value in an unexpected format). For a write, outcome is applied: QuickBooks saved the change. details.issues names the fields.
What the end user sees. Something went wrong while contacting QuickBooks. Please try again in a moment.
How to fix it
You (developer):Do not resend a write whose outcome is applied. Retrieve the object by details.objectId (or list it) to read it, and contact support with the requestId.
Support:Open the request in the dashboard; the stored qbXML response shows the unexpected value.
Example response body
{
"error": {
"type": "INTERNAL_ERROR",
"code": "QBD_RESPONSE_UNREADABLE",
"message": "QuickBooks answered, but the response could not be converted to the documented JSON shape.",
"userFacingMessage": "Something went wrong while contacting QuickBooks. Please try again in a moment.",
"httpStatusCode": 500,
"integrationCode": null,
"requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
"cause": "QuickBooks returned data that does not match the documented response schema (for example a value in an unexpected format). For a write, `outcome` is `applied`: QuickBooks saved the change. `details.issues` names the fields.",
"fixes": [
{
"actor": "developer",
"action": "Do not resend a write whose outcome is applied. Retrieve the object by details.objectId (or list it) to read it, and contact support with the requestId."
},
{
"actor": "support",
"action": "Open the request in the dashboard; the stored qbXML response shows the unexpected value."
