Enable the connection
Try itPOST /v1/end-users/{id}/connection/enable
This request changes data. It runs for real against the QuickBooks Desktop company file of the end user you choose. Use a test key (sk_test_) and a test company file.
curl -X POST https://api.desktopaccountingapi.com/v1/end-users/eu_01j9x4m6v4c8k2t7q0r5s3w1zb/connection/enable \ -H "Authorization: Bearer $DAAPI_SECRET_KEY" \ -H "Idempotency-Key: $(uuidgen)"import { DesktopAccountingApi } from "@desktopaccountingapi/quickbooks-desktop";
// Reads DAAPI_SECRET_KEY from the environment.const client = new DesktopAccountingApi();
const endUserConnection = await client.endUsers.enableConnection("eu_01j9x4m6v4c8k2t7q0r5s3w1zb");console.log(endUserConnection.id);from desktopaccountingapi import DesktopAccountingApi
# Reads DAAPI_SECRET_KEY from the environment.client = DesktopAccountingApi()
end_user_connection = client.end_users.enable_connection("eu_01j9x4m6v4c8k2t7q0r5s3w1zb")print(end_user_connection.id)using DesktopAccountingApi.QuickBooksDesktop;
// Reads DAAPI_SECRET_KEY from the environment.using var client = new DesktopAccountingApiClient();
var endUserConnection = await client.EndUsers.EnableConnectionAsync("eu_01j9x4m6v4c8k2t7q0r5s3w1zb");Console.WriteLine(endUserConnection.Id);import com.desktopaccountingapi.quickbooksdesktop.DesktopAccountingApiClient;import com.desktopaccountingapi.quickbooksdesktop.models.EndUserConnection;
// Reads DAAPI_SECRET_KEY from the environment.DesktopAccountingApiClient client = DesktopAccountingApiClient.fromEnv();
EndUserConnection endUserConnection = client.endUsers().enableConnection( "eu_01j9x4m6v4c8k2t7q0r5s3w1zb");System.out.println(endUserConnection.id());Turns a disabled connection back on. The Web Connector’s next check-in is accepted and new requests are queued again. Requests that failed while the connection was disabled are not resent. Enabling an enabled connection changes nothing.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Unique identifier for the end user.
Example
eu_01j9x4m6v4c8k2t7q0r5s3w1zbUnique identifier for the end user.
Header Parameters
Section titled “Header Parameters”Makes a write safe to retry. Repeating a key with the same request attaches to or replays the original instead of creating a second one. 1–255 printable ASCII characters, retained 7 days. Reusing a key with a different request returns 422 IDEMPOTENCY_KEY_REUSED.
Example
6f1c2a0e-1f7e-4c55-9a7a-0b2d2c9e3a10Responses
Section titled “Responses”The enabled connection.
An end user’s QuickBooks Desktop connection with its Web Connector installs and company file mismatches.
object
Unique identifier for the connection.
Always integration_connection.
When the connection was created. UTC, ISO 8601 with milliseconds.
The integration this connection uses.
Derived connection status. pending_setup: no Web Connector has finished setup. online: the Web Connector checked in recently and the last QuickBooks session opened. quickbooks_unavailable: the Web Connector checks in but QuickBooks could not be opened (statusReason holds the error code). company_file_mismatch: a different company file is open. offline: no recent check-in. disabled: turned off by the developer.
Code explaining a non-online status, when known: an error code (for example QBD_ACCESS_NOT_GRANTED), QBD_QUICKBOOKS_NOT_RESPONDING (the Web Connector checks in but QuickBooks does not answer, usually because a dialog is open) or WEB_CONNECTOR_SCHEDULE_CHANGED. With online it can be QBD_FILE_MODE_CONFLICT: QuickBooks reported a single-user/multi-user conflict and, for 2 minutes, the connection opens no session and synchronous requests fail fast with that code; or WEB_CONNECTOR_SCHEDULE_CHANGED.
When the last request for this connection was made. UTC, ISO 8601.
When the last request succeeded. UTC, ISO 8601.
When the Web Connector last checked in. UTC, ISO 8601.
The connected company file, once a session has opened.
object
Company name reported by QuickBooks.
QuickBooks product and version reported by QuickBooks.
QbXML version used with this company file.
QuickBooks edition country.
Whether QuickBooks lets this connection read personal data (employee Social Security numbers, payroll details), as the Web Connector reported in the last verified session. denied: QuickBooks omits those fields, and employee responses carry a QBD_PERSONAL_DATA_WITHHELD warning for each one. unknown: no session has reported it yet. The QuickBooks Admin changes it under Edit > Preferences > Integrated Applications > Company Preferences > Properties; the new value shows after the next session.
Unique identifier for the end user.
Whether the connection is disabled. A disabled connection refuses Web Connector check-ins and fails new requests with INTEGRATION_CONNECTION_DISABLED.
When the first Web Connector install finished setup, or null. UTC, ISO 8601 with milliseconds.
Web Connector installs (connector files) issued for this connection, newest first, at most 20.
object
Unique identifier for the Web Connector install (one connector file).
Always web_connector_install.
active: the install can check in. replaced: a newer install finished setup (for example on a new computer), or the setup flow issued a new connector file; its check-ins are refused.
When the setup flow issued the connector file. UTC, ISO 8601 with milliseconds.
Whether the end user has been shown the Web Connector password for this install.
When this install finished its first verified QuickBooks session, or null. UTC, ISO 8601 with milliseconds.
When the Web Connector first checked in with this install, or null. UTC, ISO 8601 with milliseconds.
When the Web Connector last checked in with this install, or null. UTC, ISO 8601 with milliseconds.
When the install was replaced, or null while it is active. UTC, ISO 8601 with milliseconds.
Company file mismatches in the last 30 days. total is 0 when there were none.
object
Sessions in the last 30 days in which QuickBooks had a different company file open.
Grouped by the company file QuickBooks reported, most recent first.
object
The company QuickBooks had open instead of the connected one, when QuickBooks reported it.
The file name (without folders) QuickBooks had open, when known.
true when QuickBooks could not open the connected file (HRESULT 0x80040408), usually because another company file was open.
Mismatched sessions in this group.
The first mismatched session in this group. UTC, ISO 8601 with milliseconds.
The latest mismatched session in this group. UTC, ISO 8601 with milliseconds.
Example
{ "id": "conn_01j9x4m6v4c8k2t7q0r5s3w1zc", "objectType": "integration_connection", "createdAt": "2026-10-05T16:03:59.002Z", "integrationSlug": "quickbooks_desktop", "status": "pending_setup", "statusReason": "QBD_QUICKBOOKS_NOT_RESPONDING", "companyFile": { "product": "QuickBooks Enterprise Solutions: General Business 24.0", "qbxmlVersion": "16.0", "country": "US" }, "personalDataAccess": "allowed", "endUserId": "eu_01j9x4m6v4c8k2t7q0r5s3w1zb", "setupCompletedAt": "2026-10-05T16:03:59.002Z", "installs": [ { "id": "ctr_01j9x4m6v4c8k2t7q0r5s3w1zg", "objectType": "web_connector_install", "status": "active", "createdAt": "2026-10-05T16:03:59.002Z", "setupCompletedAt": "2026-10-05T16:03:59.002Z", "firstCheckInAt": "2026-10-05T16:03:59.002Z", "lastCheckInAt": "2026-10-05T16:03:59.002Z", "replacedAt": "2026-10-05T16:03:59.002Z" } ], "companyFileMismatches": { "groups": [ { "fileName": "Acme Copy.QBW", "firstAt": "2026-10-05T16:03:59.002Z", "lastAt": "2026-10-05T16:03:59.002Z" } ] }}Headers
Section titled “Headers”Unique ID of this API call (req_...). Present on every response.
Requests allowed per window for the project (all keys together).
Requests left in the current window, as counted by the edge location that served this call.
Seconds until the current window resets.
The request is invalid. Codes: UNKNOWN_HEADER, INVALID_PARAMETER, IDEMPOTENCY_KEY_INVALID.
object
object
Error category. Use it to choose between retrying, fixing the request and asking the end user to act.
Stable error code from the error catalog. New codes may be added; a code’s meaning never changes.
Developer-facing explanation. May include IDs and field paths; never includes secrets.
A message that is safe to show to the end user.
HTTP status of the response. Every code defines one; on a request resource it is the status a synchronous call returns for the same error (for example 409 for REQUEST_CANCELED, 504 for REQUEST_EXPIRED). Nullable for compatibility only.
Native QuickBooks code when one exists: a qbXML statusCode ("3200"), an HRESULT ("0x80040414") or a Web Connector code.
The Daapi-Request-Id of this response. Include it when contacting support.
Why this error happens.
Ordered actions that resolve the error, each with the responsible actor.
object
Who can apply the fix.
What to do.
Documentation section for this code.
Repeating the identical request (with the same Idempotency-Key for writes) can succeed without changes. Also sent as the Daapi-Should-Retry header.
Whether a write took effect: applied (QuickBooks confirmed it), not_applied (it certainly did not happen), pending (sent, still processing), unknown (sent, result could not be confirmed) or not_applicable (a read).
Request field, query parameter or header the error refers to, when known.
Code-specific details, documented per code in the error catalog.
object
Examples
400 UNKNOWN_HEADER
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "UNKNOWN_HEADER", "message": "The request contains an unknown Daapi-* header.", "userFacingMessage": "This action could not be completed. Please contact the application provider.", "httpStatusCode": 400, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "Unknown Daapi-* headers are rejected so that a typo does not silently fall back to a default.", "fixes": [ { "actor": "developer", "action": "Check the header name named in `param` against the header reference." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#unknown_header", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}400 INVALID_PARAMETER
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "INVALID_PARAMETER", "message": "A request parameter is invalid.", "userFacingMessage": "This action could not be completed. Please contact the application provider.", "httpStatusCode": 400, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "A field, query parameter or header failed validation. `param` names the field.", "fixes": [ { "actor": "developer", "action": "Correct the field named in `param` using the constraints in the API reference." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#invalid_parameter", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}400 IDEMPOTENCY_KEY_INVALID
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "IDEMPOTENCY_KEY_INVALID", "message": "The Idempotency-Key header must be 1–255 printable ASCII characters.", "userFacingMessage": "This action could not be completed. Please contact the application provider.", "httpStatusCode": 400, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "The Idempotency-Key value is empty, too long or contains characters outside printable ASCII.", "fixes": [ { "actor": "developer", "action": "Use a UUID or another value of 1–255 printable ASCII characters." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#idempotency_key_invalid", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}Headers
Section titled “Headers”Unique ID of this API call (req_...). Present on every response.
Requests allowed per window for the project (all keys together).
Requests left in the current window, as counted by the edge location that served this call.
Seconds until the current window resets.
true when repeating the identical request can succeed. SDKs follow it instead of status-code heuristics.
Seconds to wait before retrying, on 429 and on retryable 503 responses when a wait is known.
The API key is missing or invalid. Codes: API_KEY_MISSING, API_KEY_INVALID.
object
object
Error category. Use it to choose between retrying, fixing the request and asking the end user to act.
Stable error code from the error catalog. New codes may be added; a code’s meaning never changes.
Developer-facing explanation. May include IDs and field paths; never includes secrets.
A message that is safe to show to the end user.
HTTP status of the response. Every code defines one; on a request resource it is the status a synchronous call returns for the same error (for example 409 for REQUEST_CANCELED, 504 for REQUEST_EXPIRED). Nullable for compatibility only.
Native QuickBooks code when one exists: a qbXML statusCode ("3200"), an HRESULT ("0x80040414") or a Web Connector code.
The Daapi-Request-Id of this response. Include it when contacting support.
Why this error happens.
Ordered actions that resolve the error, each with the responsible actor.
object
Who can apply the fix.
What to do.
Documentation section for this code.
Repeating the identical request (with the same Idempotency-Key for writes) can succeed without changes. Also sent as the Daapi-Should-Retry header.
Whether a write took effect: applied (QuickBooks confirmed it), not_applied (it certainly did not happen), pending (sent, still processing), unknown (sent, result could not be confirmed) or not_applicable (a read).
Request field, query parameter or header the error refers to, when known.
Code-specific details, documented per code in the error catalog.
object
Examples
401 API_KEY_MISSING
{ "error": { "type": "AUTHENTICATION_ERROR", "code": "API_KEY_MISSING", "message": "No API key was provided. Send Authorization: Bearer <secret key>.", "userFacingMessage": "This action is not available right now. Please contact the application provider.", "httpStatusCode": 401, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "The Authorization header is missing or is not a Bearer token.", "fixes": [ { "actor": "developer", "action": "Send Authorization: Bearer sk_live_... (or sk_test_...) from your server." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#api_key_missing", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}401 API_KEY_INVALID
{ "error": { "type": "AUTHENTICATION_ERROR", "code": "API_KEY_INVALID", "message": "The API key is invalid or has been revoked.", "userFacingMessage": "This action is not available right now. Please contact the application provider.", "httpStatusCode": 401, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "The key is malformed, unknown, or was revoked. Revocation takes effect within 30 seconds.", "fixes": [ { "actor": "developer", "action": "Create a new secret key in the dashboard and update your server configuration." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#api_key_invalid", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}Headers
Section titled “Headers”Unique ID of this API call (req_...). Present on every response.
Requests allowed per window for the project (all keys together).
Requests left in the current window, as counted by the edge location that served this call.
Seconds until the current window resets.
true when repeating the identical request can succeed. SDKs follow it instead of status-code heuristics.
Seconds to wait before retrying, on 429 and on retryable 503 responses when a wait is known.
The operation is not permitted. Codes: API_KEY_READ_ONLY.
object
object
Error category. Use it to choose between retrying, fixing the request and asking the end user to act.
Stable error code from the error catalog. New codes may be added; a code’s meaning never changes.
Developer-facing explanation. May include IDs and field paths; never includes secrets.
A message that is safe to show to the end user.
HTTP status of the response. Every code defines one; on a request resource it is the status a synchronous call returns for the same error (for example 409 for REQUEST_CANCELED, 504 for REQUEST_EXPIRED). Nullable for compatibility only.
Native QuickBooks code when one exists: a qbXML statusCode ("3200"), an HRESULT ("0x80040414") or a Web Connector code.
The Daapi-Request-Id of this response. Include it when contacting support.
Why this error happens.
Ordered actions that resolve the error, each with the responsible actor.
object
Who can apply the fix.
What to do.
Documentation section for this code.
Repeating the identical request (with the same Idempotency-Key for writes) can succeed without changes. Also sent as the Daapi-Should-Retry header.
Whether a write took effect: applied (QuickBooks confirmed it), not_applied (it certainly did not happen), pending (sent, still processing), unknown (sent, result could not be confirmed) or not_applicable (a read).
Request field, query parameter or header the error refers to, when known.
Code-specific details, documented per code in the error catalog.
object
Examples
403 API_KEY_READ_ONLY
{ "error": { "type": "PERMISSION_ERROR", "code": "API_KEY_READ_ONLY", "message": "This secret key is read-only and cannot change data.", "userFacingMessage": "This action is not available right now. Please contact the application provider.", "httpStatusCode": 403, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#api_key_read_only", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}Headers
Section titled “Headers”Unique ID of this API call (req_...). Present on every response.
Requests allowed per window for the project (all keys together).
Requests left in the current window, as counted by the edge location that served this call.
Seconds until the current window resets.
true when repeating the identical request can succeed. SDKs follow it instead of status-code heuristics.
Seconds to wait before retrying, on 429 and on retryable 503 responses when a wait is known.
The object does not exist in this project. Codes: RESOURCE_MISSING.
object
object
Error category. Use it to choose between retrying, fixing the request and asking the end user to act.
Stable error code from the error catalog. New codes may be added; a code’s meaning never changes.
Developer-facing explanation. May include IDs and field paths; never includes secrets.
A message that is safe to show to the end user.
HTTP status of the response. Every code defines one; on a request resource it is the status a synchronous call returns for the same error (for example 409 for REQUEST_CANCELED, 504 for REQUEST_EXPIRED). Nullable for compatibility only.
Native QuickBooks code when one exists: a qbXML statusCode ("3200"), an HRESULT ("0x80040414") or a Web Connector code.
The Daapi-Request-Id of this response. Include it when contacting support.
Why this error happens.
Ordered actions that resolve the error, each with the responsible actor.
object
Who can apply the fix.
What to do.
Documentation section for this code.
Repeating the identical request (with the same Idempotency-Key for writes) can succeed without changes. Also sent as the Daapi-Should-Retry header.
Whether a write took effect: applied (QuickBooks confirmed it), not_applied (it certainly did not happen), pending (sent, still processing), unknown (sent, result could not be confirmed) or not_applicable (a read).
Request field, query parameter or header the error refers to, when known.
Code-specific details, documented per code in the error catalog.
object
Examples
404 RESOURCE_MISSING
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "RESOURCE_MISSING", "message": "No such object exists in this project.", "userFacingMessage": "This action could not be completed. Please contact the application provider.", "httpStatusCode": 404, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "The ID does not exist, was deleted, or belongs to another project.", "fixes": [ { "actor": "developer", "action": "Check the ID and that the secret key belongs to the project that owns the object." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#resource_missing", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}Headers
Section titled “Headers”Unique ID of this API call (req_...). Present on every response.
Requests allowed per window for the project (all keys together).
Requests left in the current window, as counted by the edge location that served this call.
Seconds until the current window resets.
true when repeating the identical request can succeed. SDKs follow it instead of status-code heuristics.
Seconds to wait before retrying, on 429 and on retryable 503 responses when a wait is known.
The request conflicts with the current state. Codes: INTEGRATION_CONNECTION_NOT_SET_UP.
object
object
Error category. Use it to choose between retrying, fixing the request and asking the end user to act.
Stable error code from the error catalog. New codes may be added; a code’s meaning never changes.
Developer-facing explanation. May include IDs and field paths; never includes secrets.
A message that is safe to show to the end user.
HTTP status of the response. Every code defines one; on a request resource it is the status a synchronous call returns for the same error (for example 409 for REQUEST_CANCELED, 504 for REQUEST_EXPIRED). Nullable for compatibility only.
Native QuickBooks code when one exists: a qbXML statusCode ("3200"), an HRESULT ("0x80040414") or a Web Connector code.
The Daapi-Request-Id of this response. Include it when contacting support.
Why this error happens.
Ordered actions that resolve the error, each with the responsible actor.
object
Who can apply the fix.
What to do.
Documentation section for this code.
Repeating the identical request (with the same Idempotency-Key for writes) can succeed without changes. Also sent as the Daapi-Should-Retry header.
Whether a write took effect: applied (QuickBooks confirmed it), not_applied (it certainly did not happen), pending (sent, still processing), unknown (sent, result could not be confirmed) or not_applicable (a read).
Request field, query parameter or header the error refers to, when known.
Code-specific details, documented per code in the error catalog.
object
Examples
409 INTEGRATION_CONNECTION_NOT_SET_UP
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "INTEGRATION_CONNECTION_NOT_SET_UP", "message": "This end user has not finished connecting QuickBooks Desktop.", "userFacingMessage": "QuickBooks Desktop is not connected yet. Finish the connection setup to continue.", "httpStatusCode": 409, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "No Web Connector has completed setup for this end user.", "fixes": [ { "actor": "developer", "action": "Create an auth session and send the end user its authFlowUrl." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#integration_connection_not_set_up", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}Headers
Section titled “Headers”Unique ID of this API call (req_...). Present on every response.
Requests allowed per window for the project (all keys together).
Requests left in the current window, as counted by the edge location that served this call.
Seconds until the current window resets.
true when repeating the identical request can succeed. SDKs follow it instead of status-code heuristics.
Seconds to wait before retrying, on 429 and on retryable 503 responses when a wait is known.
The request is well formed but cannot be processed. Codes: IDEMPOTENCY_KEY_REUSED.
object
object
Error category. Use it to choose between retrying, fixing the request and asking the end user to act.
Stable error code from the error catalog. New codes may be added; a code’s meaning never changes.
Developer-facing explanation. May include IDs and field paths; never includes secrets.
A message that is safe to show to the end user.
HTTP status of the response. Every code defines one; on a request resource it is the status a synchronous call returns for the same error (for example 409 for REQUEST_CANCELED, 504 for REQUEST_EXPIRED). Nullable for compatibility only.
Native QuickBooks code when one exists: a qbXML statusCode ("3200"), an HRESULT ("0x80040414") or a Web Connector code.
The Daapi-Request-Id of this response. Include it when contacting support.
Why this error happens.
Ordered actions that resolve the error, each with the responsible actor.
object
Who can apply the fix.
What to do.
Documentation section for this code.
Repeating the identical request (with the same Idempotency-Key for writes) can succeed without changes. Also sent as the Daapi-Should-Retry header.
Whether a write took effect: applied (QuickBooks confirmed it), not_applied (it certainly did not happen), pending (sent, still processing), unknown (sent, result could not be confirmed) or not_applicable (a read).
Request field, query parameter or header the error refers to, when known.
Code-specific details, documented per code in the error catalog.
object
Examples
422 IDEMPOTENCY_KEY_REUSED
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "IDEMPOTENCY_KEY_REUSED", "message": "This Idempotency-Key was already used with a different request.", "userFacingMessage": "This action could not be completed. Please contact the application provider.", "httpStatusCode": 422, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "A key identifies one logical request. The method, path, end user or body differs from the first use of this key.", "fixes": [ { "actor": "developer", "action": "Generate a new key for each logical request and reuse it only for retries of that request." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#idempotency_key_reused", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}Headers
Section titled “Headers”Unique ID of this API call (req_...). Present on every response.
Requests allowed per window for the project (all keys together).
Requests left in the current window, as counted by the edge location that served this call.
Seconds until the current window resets.
true when repeating the identical request can succeed. SDKs follow it instead of status-code heuristics.
Seconds to wait before retrying, on 429 and on retryable 503 responses when a wait is known.
Too many requests. Codes: RATE_LIMITED.
object
object
Error category. Use it to choose between retrying, fixing the request and asking the end user to act.
Stable error code from the error catalog. New codes may be added; a code’s meaning never changes.
Developer-facing explanation. May include IDs and field paths; never includes secrets.
A message that is safe to show to the end user.
HTTP status of the response. Every code defines one; on a request resource it is the status a synchronous call returns for the same error (for example 409 for REQUEST_CANCELED, 504 for REQUEST_EXPIRED). Nullable for compatibility only.
Native QuickBooks code when one exists: a qbXML statusCode ("3200"), an HRESULT ("0x80040414") or a Web Connector code.
The Daapi-Request-Id of this response. Include it when contacting support.
Why this error happens.
Ordered actions that resolve the error, each with the responsible actor.
object
Who can apply the fix.
What to do.
Documentation section for this code.
Repeating the identical request (with the same Idempotency-Key for writes) can succeed without changes. Also sent as the Daapi-Should-Retry header.
Whether a write took effect: applied (QuickBooks confirmed it), not_applied (it certainly did not happen), pending (sent, still processing), unknown (sent, result could not be confirmed) or not_applicable (a read).
Request field, query parameter or header the error refers to, when known.
Code-specific details, documented per code in the error catalog.
object
Examples
429 RATE_LIMITED
{ "error": { "type": "RATE_LIMIT_ERROR", "code": "RATE_LIMITED", "message": "Too many requests for this project. Retry after the time in Retry-After.", "userFacingMessage": "Too many actions are in progress. Please try again in a moment.", "httpStatusCode": 429, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#rate_limited", "retryable": true, "outcome": "not_applied", "param": null, "details": {} }}Headers
Section titled “Headers”Unique ID of this API call (req_...). Present on every response.
Requests allowed per window for the project (all keys together).
Requests left in the current window, as counted by the edge location that served this call.
Seconds until the current window resets.
true when repeating the identical request can succeed. SDKs follow it instead of status-code heuristics.
Seconds to wait before retrying, on 429 and on retryable 503 responses when a wait is known.
Unexpected server error. Codes: INTERNAL_ERROR.
object
object
Error category. Use it to choose between retrying, fixing the request and asking the end user to act.
Stable error code from the error catalog. New codes may be added; a code’s meaning never changes.
Developer-facing explanation. May include IDs and field paths; never includes secrets.
A message that is safe to show to the end user.
HTTP status of the response. Every code defines one; on a request resource it is the status a synchronous call returns for the same error (for example 409 for REQUEST_CANCELED, 504 for REQUEST_EXPIRED). Nullable for compatibility only.
Native QuickBooks code when one exists: a qbXML statusCode ("3200"), an HRESULT ("0x80040414") or a Web Connector code.
The Daapi-Request-Id of this response. Include it when contacting support.
Why this error happens.
Ordered actions that resolve the error, each with the responsible actor.
object
Who can apply the fix.
What to do.
Documentation section for this code.
Repeating the identical request (with the same Idempotency-Key for writes) can succeed without changes. Also sent as the Daapi-Should-Retry header.
Whether a write took effect: applied (QuickBooks confirmed it), not_applied (it certainly did not happen), pending (sent, still processing), unknown (sent, result could not be confirmed) or not_applicable (a read).
Request field, query parameter or header the error refers to, when known.
Code-specific details, documented per code in the error catalog.
object
Examples
500 INTERNAL_ERROR
{ "error": { "type": "INTERNAL_ERROR", "code": "INTERNAL_ERROR", "message": "An unexpected error occurred on our side.", "userFacingMessage": "Something went wrong. Please try again in a moment.", "httpStatusCode": 500, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "An unexpected server error. `outcome` says whether a write may have reached QuickBooks.", "fixes": [ { "actor": "developer", "action": "Retry reads. For writes, check `outcome` first and never resend when it is unknown." }, { "actor": "support", "action": "Contact support with the requestId." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#internal_error", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}Headers
Section titled “Headers”Unique ID of this API call (req_...). Present on every response.
Requests allowed per window for the project (all keys together).
Requests left in the current window, as counted by the edge location that served this call.
Seconds until the current window resets.
true when repeating the identical request can succeed. SDKs follow it instead of status-code heuristics.
Seconds to wait before retrying, on 429 and on retryable 503 responses when a wait is known.
QuickBooks Desktop or the service is not available. Codes: SERVICE_UNAVAILABLE.
object
object
Error category. Use it to choose between retrying, fixing the request and asking the end user to act.
Stable error code from the error catalog. New codes may be added; a code’s meaning never changes.
Developer-facing explanation. May include IDs and field paths; never includes secrets.
A message that is safe to show to the end user.
HTTP status of the response. Every code defines one; on a request resource it is the status a synchronous call returns for the same error (for example 409 for REQUEST_CANCELED, 504 for REQUEST_EXPIRED). Nullable for compatibility only.
Native QuickBooks code when one exists: a qbXML statusCode ("3200"), an HRESULT ("0x80040414") or a Web Connector code.
The Daapi-Request-Id of this response. Include it when contacting support.
Why this error happens.
Ordered actions that resolve the error, each with the responsible actor.
object
Who can apply the fix.
What to do.
Documentation section for this code.
Repeating the identical request (with the same Idempotency-Key for writes) can succeed without changes. Also sent as the Daapi-Should-Retry header.
Whether a write took effect: applied (QuickBooks confirmed it), not_applied (it certainly did not happen), pending (sent, still processing), unknown (sent, result could not be confirmed) or not_applicable (a read).
Request field, query parameter or header the error refers to, when known.
Code-specific details, documented per code in the error catalog.
object
Examples
503 SERVICE_UNAVAILABLE
{ "error": { "type": "INTERNAL_ERROR", "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. The request was not queued.", "userFacingMessage": "Something went wrong. Please try again in a moment.", "httpStatusCode": 503, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "A dependency was unavailable before the request was accepted. Nothing reached QuickBooks.", "fixes": [ { "actor": "developer", "action": "Retry with backoff." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#service_unavailable", "retryable": true, "outcome": "not_applied", "param": null, "details": {} }}Headers
Section titled “Headers”Unique ID of this API call (req_...). Present on every response.
Requests allowed per window for the project (all keys together).
Requests left in the current window, as counted by the edge location that served this call.
Seconds until the current window resets.
true when repeating the identical request can succeed. SDKs follow it instead of status-code heuristics.
Seconds to wait before retrying, on 429 and on retryable 503 responses when a wait is known.