Retrieve a job type
Try itGET /v1/quickbooks-desktop/job-types/{id}
Sends a real request to the API from your browser. A test key (sk_test_) is recommended.
Headers (3 optional)
curl https://api.desktopaccountingapi.com/v1/quickbooks-desktop/job-types/80000001-1234567890 \ -H "Authorization: Bearer $DAAPI_SECRET_KEY" \ -H "Daapi-End-User-Id: $DAAPI_END_USER_ID"import { DesktopAccountingApi } from "@desktopaccountingapi/quickbooks-desktop";
// Reads DAAPI_SECRET_KEY from the environment.const client = new DesktopAccountingApi({ endUserId: process.env["DAAPI_END_USER_ID"] });
const jobType = await client.qbd.jobTypes.retrieve("80000001-1234567890");console.log(jobType.id);import os
from desktopaccountingapi import DesktopAccountingApi
# Reads DAAPI_SECRET_KEY from the environment.client = DesktopAccountingApi(end_user_id=os.environ["DAAPI_END_USER_ID"])
job_type = client.qbd.job_types.retrieve("80000001-1234567890")print(job_type.id)using DesktopAccountingApi.QuickBooksDesktop;
// Reads DAAPI_SECRET_KEY from the environment.using var client = new DesktopAccountingApiClient(new ClientOptions{ EndUserId = Environment.GetEnvironmentVariable("DAAPI_END_USER_ID"),});
var jobType = await client.Qbd.JobTypes.RetrieveAsync("80000001-1234567890");Console.WriteLine(jobType.Id);import com.desktopaccountingapi.quickbooksdesktop.DesktopAccountingApiClient;import com.desktopaccountingapi.quickbooksdesktop.models.JobType;
// Reads DAAPI_SECRET_KEY from the environment.DesktopAccountingApiClient client = DesktopAccountingApiClient.fromEnv() .forEndUser(System.getenv("DAAPI_END_USER_ID"));
JobType jobType = client.qbd().jobTypes().retrieve("80000001-1234567890");System.out.println(jobType.id());Returns one job type by its QuickBooks ID. An unknown ID returns 404 QBD_OBJECT_NOT_FOUND.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”QuickBooks ID of the job type.
Example
80000001-1234567890QuickBooks ID of the job type.
Header Parameters
Section titled “Header Parameters”The end user whose QuickBooks company file this request uses. Conductor-End-User-Id is accepted as an alias.
Example
eu_01j9x4m6v4c8k2t7q0r5s3w1zbHow long to wait for QuickBooks, in seconds (1–300). Conductor-Timeout-Seconds is accepted as an alias. Default 90, or 60 for the health check. If the request has not been sent by then it is canceled (504 REQUEST_TIMEOUT_NOT_SENT); if it was sent it keeps running (504 QBD_REQUEST_TIMEOUT).
Example
90Send respond-async to get 202 Accepted with a request resource immediately instead of waiting for QuickBooks.
Example
respond-asyncAsync only: the latest time, in seconds from now (10 to 86400), the request may still be sent to QuickBooks. Default 3600.
Example
3600Responses
Section titled “Responses”The job type.
Job type as stored in QuickBooks Desktop.
object
QuickBooks-assigned ID of this job type.
Type of this object.
When this job type was created, as an ISO 8601 date-time with the QuickBooks computer’s UTC offset.
When this job type was last changed, as an ISO 8601 date-time with the QuickBooks computer’s UTC offset. Whole seconds: a second change within the same second keeps this value, so incremental syncs should overlap updatedAfter and deduplicate by id and revisionNumber.
Current revision of this job type. Send it unchanged when updating; a stale value is rejected. QuickBooks changes it at most once per second, so a second edit within the same second keeps the same value. This API spaces its own consecutive writes to one object by over a second; edits made elsewhere in the same second are not detected.
Name of this job type, unique within its parent level.
Full hierarchical name of this job type: parent names and its own name separated by colons.
Whether this job type is active. Inactive objects stay in QuickBooks but are hidden from most lists.
Depth in the hierarchy: 0 for top-level objects, 1 for their children and so on.
Example
{ "objectType": "qbd_job_type", "createdAt": "2026-10-05T09:14:03-07:00", "updatedAt": "2026-10-05T09:14:03-07:00"}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.
Accepted in async mode (Prefer: respond-async). Poll Location or wait for a webhook; the request’s result holds the success body.
object
Unique identifier for the request.
Always request.
When the request was received. UTC, ISO 8601 with milliseconds.
Unique identifier for the project.
Unique identifier for the end user.
The connection that carried the request; null when the call was rejected before the end user had a connection (no setup link created yet).
The API operation, for example endUsers.passthrough or qbd.healthCheck.
HTTP method of the original call.
Path of the original call.
sync when the caller waited for the result.
queued: accepted and waiting for its turn or the next Web Connector check-in. waiting_for_connection: async request waiting for an offline connection. sent: handed to QuickBooks; it can no longer be canceled. succeeded and failed are final. canceled: canceled before it was sent. outcome_unknown: a write was sent and its result could not be confirmed.
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).
When the request was handed to the Web Connector. UTC, ISO 8601.
When the request reached a final status. UTC, ISO 8601.
Milliseconds from creation to completion.
Whether the call sent an Idempotency-Key.
An earlier request with the same Idempotency-Key that ended before reaching QuickBooks.
Why a queued request is waiting. quickbooks_not_responding: the Web Connector started a session but QuickBooks has not answered it (usually a QuickBooks dialog is open; see diagnosis). file_mode_conflict: the company file was held in single-user mode or by another program; the connection opens QuickBooks again at the retryAt of the file_mode_conflict diagnosis cause, and the request runs then unless its deadline or queue TTL expires first. null once the request was sent.
Position in this connection’s queue (1 = next), while queued.
Async requests only: the latest time the request may still be sent. UTC, ISO 8601.
Where the time went.
object
Milliseconds from creation until the request was sent to QuickBooks.
Milliseconds from sending until QuickBooks answered.
Milliseconds from creation to completion.
Native QuickBooks details.
object
QbXML version used.
QbXML newMessageSetID sent with a write.
QbXML statusCode of the first response element.
QbXML statusSeverity (Info, Warn or Error).
QuickBooks warnings (statusSeverity="Warn"), values the API read leniently from a damaged company file, and personal-data fields QuickBooks did not share. The response body never drops a record for these; affected values are null.
object
QBD_WARNING for a QuickBooks warning status; QBD_VALUE_UNREADABLE when a value in the response was garbled and is returned as null; QBD_MARKUP_REPAIRED when malformed XML text was kept as text; QBD_PERSONAL_DATA_WITHHELD when QuickBooks did not share a personal-data field (an employee’s ssn) because the integration may not access personal data; the value is null whether or not the file has one. Each code is described on the error reference page under Warnings.
QbXML statusCode of a QuickBooks warning; null for warnings about the response data.
What happened, including the text QuickBooks sent for unreadable values.
Where in result the affected value is, such as data[2].lines[0].amount; null for QuickBooks warning statuses.
true when an outcome_unknown write was resolved by asking QuickBooks for its stored result.
Lifecycle steps in order.
object
When the step happened. UTC, ISO 8601 with milliseconds.
Step, usually a status (queued, waiting, sent, succeeded, diagnosed, …).
Extra detail, for example the waiting reason or diagnosis cause.
Milliseconds since the request was created.
Why a request is waiting, or why it timed out or expired. The server cannot see the end user’s screen; it ranks causes from Web Connector check-ins, whether QuickBooks answered, native connection errors, the company file identity and the queue.
object
When the diagnosis was made. UTC, ISO 8601 with milliseconds.
The most likely cause in one line.
What the server observed about the end user’s Web Connector.
object
Last sign of the Web Connector (a check-in or a call inside a session). UTC, ISO 8601.
Last Web Connector check-in. UTC, ISO 8601.
Typical interval between recent check-ins, in seconds.
Seconds since lastSeenAt.
Whether a Web Connector session is open now.
When the open session started. UTC, ISO 8601.
Whether QuickBooks answered the open session; null without a session.
Recent consecutive sessions in which QuickBooks never answered.
Error code of the latest QuickBooks connection error, while it persists.
Probable causes, most likely first.
object
Stable cause code. New codes may be added.
How strongly the observations point at this cause.
One-line description of the cause.
What the server observed and why it points at this cause.
Actions that resolve the cause, each with the responsible actor.
object
Who can apply the fix.
What to do.
Cause-specific observations, for example connectionErrorCode or silentForMs.
object
Troubleshooting section for this cause.
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
The response body the original call returned (or would have returned) on success; null otherwise.
true when the result existed but is past the payload retention period (15 days, or 24 hours with payload capture off).
Example
{ "id": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "objectType": "request", "createdAt": "2026-10-05T16:03:59.002Z", "projectId": "proj_01j9x4m6v4c8k2t7q0r5s3w1zf", "endUserId": "eu_01j9x4m6v4c8k2t7q0r5s3w1zb", "connectionId": "conn_01j9x4m6v4c8k2t7q0r5s3w1zc", "operationId": "qbd.healthCheck", "method": "GET", "path": "/v1/quickbooks-desktop/health-check", "mode": "sync", "status": "queued", "outcome": "applied", "waitingReason": "awaiting_check_in", "warnings": [ { "code": "QBD_WARNING" } ], "timeline": [ { "at": "2026-10-05T16:03:59.002Z" } ], "diagnosis": { "at": "2026-10-05T16:03:59.002Z", "summary": "QuickBooks Desktop probably has a dialog window open.", "probableCauses": [ { "code": "quickbooks_modal_dialog", "likelihood": "high", "fixes": [ { "actor": "developer" } ] } ] }, "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_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_modal_dialog_open", "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.
Path of the request resource, /v1/requests/{id}.
respond-async when async mode was honored.
The request is invalid. Codes: UNKNOWN_HEADER, END_USER_ID_MISSING, INVALID_PARAMETER, UNKNOWN_PARAMETER.
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 END_USER_ID_MISSING
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "END_USER_ID_MISSING", "message": "QuickBooks Desktop operations require the Daapi-End-User-Id header.", "userFacingMessage": "This action could not be completed. Please contact the application provider.", "httpStatusCode": 400, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "The request did not say which end user, and therefore which QuickBooks company file, it is for.", "fixes": [ { "actor": "developer", "action": "Send Daapi-End-User-Id with the end user's ID (eu_...)." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#end_user_id_missing", "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 UNKNOWN_PARAMETER
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "UNKNOWN_PARAMETER", "message": "The request contains a field this operation does not accept.", "userFacingMessage": "This action could not be completed. Please contact the application provider.", "httpStatusCode": 400, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "Request bodies are strict. A misspelled or unsupported field is rejected instead of being ignored.", "fixes": [ { "actor": "developer", "action": "Remove or rename the field named in `param`." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#unknown_parameter", "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.
Billing blocks production data requests. Codes: BILLING_REQUIRED, PAYMENT_FAILED.
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
402 BILLING_REQUIRED
{ "error": { "type": "BILLING_ERROR", "code": "BILLING_REQUIRED", "message": "Production data requests are paused because the organization has no active subscription.", "userFacingMessage": "This action is not available right now. Please contact the application provider.", "httpStatusCode": 402, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#billing_required", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}402 PAYMENT_FAILED
{ "error": { "type": "BILLING_ERROR", "code": "PAYMENT_FAILED", "message": "Production data requests are paused because payment failed.", "userFacingMessage": "This action is not available right now. Please contact the application provider.", "httpStatusCode": 402, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#payment_failed", "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: INTEGRATION_CONNECTION_DISABLED, PERMISSION_DENIED, QBD_INSUFFICIENT_PERMISSION.
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 INTEGRATION_CONNECTION_DISABLED
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "INTEGRATION_CONNECTION_DISABLED", "message": "This connection is disabled.", "userFacingMessage": "This QuickBooks connection is turned off. Please contact the application provider.", "httpStatusCode": 403, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "The connection was disabled in the dashboard.", "fixes": [ { "actor": "developer", "action": "Enable the connection in the dashboard, or create a new auth session." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#integration_connection_disabled", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}403 PERMISSION_DENIED
{ "error": { "type": "PERMISSION_ERROR", "code": "PERMISSION_DENIED", "message": "This project is not allowed to perform this operation.", "userFacingMessage": "This action is not available right now. Please contact the application provider.", "httpStatusCode": 403, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "The operation is not available for this project or object in its current state.", "fixes": [ { "actor": "developer", "action": "Check the project and object state in the dashboard." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#permission_denied", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}403 QBD_INSUFFICIENT_PERMISSION
{ "error": { "type": "INTEGRATION_ERROR", "code": "QBD_INSUFFICIENT_PERMISSION", "message": "The QuickBooks user or the integration lacks permission for this operation.", "userFacingMessage": "This connection does not have permission for this action in QuickBooks Desktop. Ask your QuickBooks Admin to update the permissions.", "httpStatusCode": 403, "integrationCode": "3260", "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "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 in single-user mode, choose Edit > Preferences > Integrated Applications > Company Preferences, select the application, click Properties, tick \"Allow this application to access personal data such as Social Security Number and customer credit card information\" and click OK twice." }, { "actor": "end_user", "action": "For status 3261 when that checkbox is gray: the connector file was added before personal data could be requested. Open a new setup link, choose \"Enable payroll access\", remove the old row in the Web Connector and add the new connector file, ticking the personal-data checkbox when QuickBooks asks." }, { "actor": "developer", "action": "Check integrationCode, then show the end user the matching fix; nothing was changed. For status 3261, send the end user a new setup link if their checkbox is gray, and turn on \"Request access to personal data\" in dashboard Settings if your app always needs payroll or employee data." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_insufficient_permission", "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, QBD_OBJECT_NOT_FOUND.
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": {} }}404 QBD_OBJECT_NOT_FOUND
{ "error": { "type": "INTEGRATION_ERROR", "code": "QBD_OBJECT_NOT_FOUND", "message": "The QuickBooks object does not exist.", "userFacingMessage": "The requested record was not found in QuickBooks Desktop.", "httpStatusCode": 404, "integrationCode": "500", "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "The ID does not exist in this company file, or the object was deleted in QuickBooks.", "fixes": [ { "actor": "developer", "action": "Check the ID, or list the objects to find the current one." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_object_not_found", "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, QBD_COMPANY_FILE_MISMATCH.
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": {} }}409 QBD_COMPANY_FILE_MISMATCH
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "QBD_COMPANY_FILE_MISMATCH", "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_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_company_file_mismatch", "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: QBD_FIELD_UNSUPPORTED_BY_VERSION, QBD_REGION_UNSUPPORTED, QBD_REQUEST_ERROR, QBD_FEATURE_NOT_ENABLED.
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 QBD_FIELD_UNSUPPORTED_BY_VERSION
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "QBD_FIELD_UNSUPPORTED_BY_VERSION", "message": "externalId needs qbXML 8.0; the connected QuickBooks supports 7.0.", "userFacingMessage": "This feature needs a newer version of QuickBooks Desktop. Please contact the application provider.", "httpStatusCode": 422, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_field_unsupported_by_version", "retryable": false, "outcome": "not_applied", "param": "externalId", "details": { "minimumQbxmlVersion": "8.0", "qbxmlVersion": "7.0" } }}422 QBD_REGION_UNSUPPORTED
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "QBD_REGION_UNSUPPORTED", "message": "The connected QuickBooks Desktop is not a US edition.", "userFacingMessage": "This version of QuickBooks Desktop is not supported. Only US editions can be connected.", "httpStatusCode": 422, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "Desktop Accounting API supports US editions of QuickBooks Desktop. Canadian, UK and Australian editions use different schemas.", "fixes": [ { "actor": "developer", "action": "Use passthrough for non-US editions at your own risk, or connect a US edition." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_region_unsupported", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}422 QBD_REQUEST_ERROR
{ "error": { "type": "INTEGRATION_ERROR", "code": "QBD_REQUEST_ERROR", "message": "QuickBooks Desktop rejected the request.", "userFacingMessage": "QuickBooks Desktop did not accept this change. Please contact the application provider.", "httpStatusCode": 422, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "QuickBooks returned an error status without a more specific mapping. `integrationCode` holds the qbXML statusCode and `details.qbxmlStatusMessage` its message. When QuickBooks could not parse the request at all (HRESULT 0x80040400, usually a malformed passthrough body: a missing wrapper element, a wrong element name or order), `integrationCode` and `details.hresult` hold that HRESULT; QuickBooks processed nothing, so the outcome is `not_applied`.", "fixes": [ { "actor": "developer", "action": "Read details.qbxmlStatusMessage (or details.quickbooksMessage) and correct the request. For a parse error, check the qbXML against the QuickBooks SDK reference before sending it again." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_request_error", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}422 QBD_FEATURE_NOT_ENABLED
{ "error": { "type": "INTEGRATION_ERROR", "code": "QBD_FEATURE_NOT_ENABLED", "message": "The QuickBooks feature this request needs is turned off or not available in this edition.", "userFacingMessage": "This feature is not turned on in QuickBooks Desktop.", "httpStatusCode": 422, "integrationCode": "3250", "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "For example, inventory sites need Advanced Inventory, and some features must be turned on in Preferences.", "fixes": [ { "actor": "end_user", "action": "Turn on the feature in QuickBooks Preferences, if the edition supports it." }, { "actor": "developer", "action": "Avoid the feature for this end user." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_feature_not_enabled", "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, CONNECTION_QUEUE_FULL.
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": {} }}429 CONNECTION_QUEUE_FULL
{ "error": { "type": "RATE_LIMIT_ERROR", "code": "CONNECTION_QUEUE_FULL", "message": "This connection has too many pending requests.", "userFacingMessage": "Too many actions are in progress. Please try again in a moment.", "httpStatusCode": 429, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#connection_queue_full", "retryable": true, "outcome": "not_applied", "param": null, "details": { "reason": "pending_requests", "limit": 200 } }}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.
The result could not be confirmed. Codes: QBD_READ_INTERRUPTED.
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
502 QBD_READ_INTERRUPTED
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "QBD_READ_INTERRUPTED", "message": "The connection to QuickBooks broke while reading; the automatic retry also failed.", "userFacingMessage": "The connection to QuickBooks Desktop was interrupted. Please try again.", "httpStatusCode": 502, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "The Web Connector session ended before QuickBooks returned the result of a read.", "fixes": [ { "actor": "developer", "action": "Retry the read." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_read_interrupted", "retryable": true, "outcome": "not_applicable", "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, INTEGRATION_CONNECTION_NOT_ACTIVE, QBD_CONNECTION_ERROR, QBD_CANNOT_START, QBD_STARTING, QBD_MODAL_DIALOG_OPEN, QBD_QUICKBOOKS_NOT_RESPONDING, QBD_WRONG_COMPANY_FILE_OPEN, QBD_COMPANY_FILE_NOT_FOUND, QBD_FILE_MODE_CONFLICT, QBD_ADMIN_REQUIRED, QBD_ACCESS_NOT_GRANTED, QBD_VERSION_UNSUPPORTED, QBD_RESPONSE_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": {} }}503 INTEGRATION_CONNECTION_NOT_ACTIVE
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "INTEGRATION_CONNECTION_NOT_ACTIVE", "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_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#integration_connection_not_active", "retryable": true, "outcome": "not_applied", "param": null, "details": {} }}503 QBD_CONNECTION_ERROR
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "QBD_CONNECTION_ERROR", "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_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_connection_error", "retryable": true, "outcome": "not_applied", "param": null, "details": {} }}503 QBD_CANNOT_START
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "QBD_CANNOT_START", "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_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_cannot_start", "retryable": true, "outcome": "not_applied", "param": null, "details": {} }}503 QBD_STARTING
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "QBD_STARTING", "message": "QuickBooks Desktop is still starting.", "userFacingMessage": "QuickBooks Desktop is still opening. Please try again in a minute.", "httpStatusCode": 503, "integrationCode": "0x80040424", "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "QuickBooks had not finished opening the company file when the Web Connector connected.", "fixes": [ { "actor": "developer", "action": "Retry after a short wait." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_starting", "retryable": true, "outcome": "not_applied", "param": null, "details": {} }}503 QBD_MODAL_DIALOG_OPEN
{ "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_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_modal_dialog_open", "retryable": true, "outcome": "not_applied", "param": null, "details": {} }}503 QBD_QUICKBOOKS_NOT_RESPONDING
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "QBD_QUICKBOOKS_NOT_RESPONDING", "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_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_quickbooks_not_responding", "retryable": true, "outcome": "not_applied", "param": null, "details": {} }}503 QBD_WRONG_COMPANY_FILE_OPEN
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "QBD_WRONG_COMPANY_FILE_OPEN", "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_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_wrong_company_file_open", "retryable": true, "outcome": "not_applied", "param": null, "details": {} }}503 QBD_COMPANY_FILE_NOT_FOUND
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "QBD_COMPANY_FILE_NOT_FOUND", "message": "QuickBooks could not open the company file at its stored location.", "userFacingMessage": "QuickBooks Desktop could not find the company file. If it was moved or renamed, open it in QuickBooks, then try again.", "httpStatusCode": 503, "integrationCode": "0x80040403", "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "The company file was moved, renamed or deleted, or QuickBooks was closed and no file path was available.", "fixes": [ { "actor": "end_user", "action": "Open the company file in QuickBooks Desktop and leave it open." }, { "actor": "developer", "action": "Reset the stored company file path (dashboard, or POST /v1/end-users/{id}/reset-company-file with mode `path`)." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_company_file_not_found", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}503 QBD_FILE_MODE_CONFLICT
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "QBD_FILE_MODE_CONFLICT", "message": "The company file is open in a mode that does not allow this connection.", "userFacingMessage": "The QuickBooks company file is open in single-user mode or in use by another program. Ask whoever has it open to finish, or choose File > Switch to Multi-user Mode in QuickBooks. If you are switching modes yourself, let the Web Connector finish first. The connection tries again in a few minutes.", "httpStatusCode": 503, "integrationCode": "0x80040410", "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "The file is open in single-user mode by another application or user, or in a different file mode than requested (also while someone switches between single-user and multi-user mode). After this error the connection opens no QuickBooks session for 2 minutes, so it does not race the file being reopened. A synchronous request sent inside that window fails at once with this code, `details.retryAt` and `Retry-After`; nothing is sent. Queued requests wait (`waitingReason: file_mode_conflict`) and run after the window, unless their deadline or queue TTL expires first, or the conflict repeats until their budget of failed sessions is spent.", "fixes": [ { "actor": "end_user", "action": "Ask whoever has the file open in single-user mode to finish or switch to multi-user mode, and close other programs that hold the file. Let the Web Connector finish its update (or exit it) before switching modes." }, { "actor": "developer", "action": "Retry after details.retryAt (Retry-After), or send the request asynchronously (Prefer: respond-async) with a queue TTL that outlasts the window so it runs then." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_file_mode_conflict", "retryable": true, "outcome": "not_applied", "param": null, "details": {} }}503 QBD_ADMIN_REQUIRED
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "QBD_ADMIN_REQUIRED", "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_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_admin_required", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}503 QBD_ACCESS_NOT_GRANTED
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "QBD_ACCESS_NOT_GRANTED", "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_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_access_not_granted", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}503 QBD_VERSION_UNSUPPORTED
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "QBD_VERSION_UNSUPPORTED", "message": "The installed QuickBooks Desktop version is not supported.", "userFacingMessage": "This version of QuickBooks Desktop is too old to connect. Update QuickBooks Desktop, then try again.", "httpStatusCode": 503, "integrationCode": "0x80040404", "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "QuickBooks reports a qbXML version below 13.0 (QuickBooks 2014) or does not support the requested version.", "fixes": [ { "actor": "end_user", "action": "Update QuickBooks Desktop to a supported release." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_version_unsupported", "retryable": false, "outcome": "not_applied", "param": null, "details": {} }}503 QBD_RESPONSE_UNAVAILABLE
{ "error": { "type": "INTERNAL_ERROR", "code": "QBD_RESPONSE_UNAVAILABLE", "message": "QuickBooks answered, but its stored response could not be read.", "userFacingMessage": "Something went wrong. Please try again in a moment.", "httpStatusCode": 503, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "A read reached QuickBooks, but its response could not be read back from storage, even after a retry, so the result (for a retrieve, whether the record exists) is unknown. Reads change nothing in QuickBooks. The request is failed and not billed.", "fixes": [ { "actor": "developer", "action": "Retry the read; it is safe to repeat." }, { "actor": "support", "action": "If it keeps happening, contact support with the requestId." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_response_unavailable", "retryable": true, "outcome": "not_applicable", "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 timed out. Codes: REQUEST_TIMEOUT_NOT_SENT, QBD_REQUEST_TIMEOUT.
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
504 REQUEST_TIMEOUT_NOT_SENT
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "REQUEST_TIMEOUT_NOT_SENT", "message": "The request timed out before it was sent to QuickBooks and was canceled.", "userFacingMessage": "QuickBooks Desktop was not available in time. Please try again.", "httpStatusCode": 504, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "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." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#request_timeout_not_sent", "retryable": true, "outcome": "not_applied", "param": null, "details": {} }}504 QBD_REQUEST_TIMEOUT
{ "error": { "type": "INTEGRATION_CONNECTION_ERROR", "code": "QBD_REQUEST_TIMEOUT", "message": "QuickBooks is still processing the request; the wait timed out.", "userFacingMessage": "QuickBooks Desktop is taking longer than usual. The action is still in progress.", "httpStatusCode": 504, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "The request reached QuickBooks but did not finish within Daapi-Timeout-Seconds. It keeps running.", "fixes": [ { "actor": "developer", "action": "Poll GET /v1/requests/{details.requestId}?waitSeconds=60 for the result. Do not resend the request." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_request_timeout", "retryable": false, "outcome": "pending", "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.