List entities
Try itGET /v1/quickbooks-desktop/entities
Sends a real request to the API from your browser. A test key (sk_test_) is recommended.
Query parameters (12 optional)
Headers (3 optional)
curl "https://api.desktopaccountingapi.com/v1/quickbooks-desktop/entities?limit=10" \ -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"] });
for await (const entity of client.qbd.entities.list({ limit: 10 })) { console.log(entity.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"])
for entity in client.qbd.entities.list(limit=10): print(entity.id)using DesktopAccountingApi.QuickBooksDesktop;using DesktopAccountingApi.QuickBooksDesktop.Models;
// Reads DAAPI_SECRET_KEY from the environment.using var client = new DesktopAccountingApiClient(new ClientOptions{ EndUserId = Environment.GetEnvironmentVariable("DAAPI_END_USER_ID"),});
await foreach (var entity in client.Qbd.Entities.ListAsync(new EntityListParams { Limit = 10 })){ Console.WriteLine(entity.Id);}import com.desktopaccountingapi.quickbooksdesktop.DesktopAccountingApiClient;import com.desktopaccountingapi.quickbooksdesktop.models.Entity;import com.desktopaccountingapi.quickbooksdesktop.models.EntityListParams;
// Reads DAAPI_SECRET_KEY from the environment.DesktopAccountingApiClient client = DesktopAccountingApiClient.fromEnv() .forEndUser(System.getenv("DAAPI_END_USER_ID"));
for (Entity entity : client.qbd().entities().list(new EntityListParams().limit(10))) { System.out.println(entity.id());}Returns the entities that match your filters. Results are paged: pass nextCursor as cursor until hasMore is false. A cursor lives only inside the current QuickBooks session, so request the next page promptly; an expired cursor returns 410 CURSOR_EXPIRED. See Pagination.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”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
3600Query Parameters
Section titled “Query Parameters”Return only the entities with these QuickBooks IDs. Cannot be combined with fullNames, status, updatedAfter, updatedBefore, nameStartsWith, nameContains, nameEndsWith, nameFrom, nameTo. Returns every match in one page (nextCursor is null); limit is ignored.
Return only the entities with these QuickBooks IDs. Cannot be combined with fullNames, status, updatedAfter, updatedBefore, nameStartsWith, nameContains, nameEndsWith, nameFrom, nameTo. Returns every match in one page (nextCursor is null); limit is ignored.
Return only the entities with these full names (case-insensitive, including parent names separated by colons). Cannot be combined with ids, status, updatedAfter, updatedBefore, nameStartsWith, nameContains, nameEndsWith, nameFrom, nameTo. Returns every match in one page (nextCursor is null); limit is ignored.
Return only the entities with these full names (case-insensitive, including parent names separated by colons). Cannot be combined with ids, status, updatedAfter, updatedBefore, nameStartsWith, nameContains, nameEndsWith, nameFrom, nameTo. Returns every match in one page (nextCursor is null); limit is ignored.
Maximum number of entities per page, 1 to 150. Ignored with ids, fullNames, which return every match in one page.
Maximum number of entities per page, 1 to 150. Ignored with ids, fullNames, which return every match in one page.
Filter entities by active state. Defaults to active ones only. Cannot be combined with ids, fullNames.
Return entities changed on or after this date or date-time (QuickBooks local time unless an offset is given). Cannot be combined with ids, fullNames.
Example
2026-10-05T09:14:03-07:00Return entities changed on or after this date or date-time (QuickBooks local time unless an offset is given). Cannot be combined with ids, fullNames.
Return entities changed on or before this date or date-time (QuickBooks local time unless an offset is given). Cannot be combined with ids, fullNames.
Example
2026-10-05T09:14:03-07:00Return entities changed on or before this date or date-time (QuickBooks local time unless an offset is given). Cannot be combined with ids, fullNames.
Return entities whose name starts with this text (case-insensitive). Cannot be combined with ids, fullNames, nameFrom, nameTo.
Return entities whose name starts with this text (case-insensitive). Cannot be combined with ids, fullNames, nameFrom, nameTo.
Return entities whose name contains this text (case-insensitive). Cannot be combined with ids, fullNames, nameFrom, nameTo.
Return entities whose name contains this text (case-insensitive). Cannot be combined with ids, fullNames, nameFrom, nameTo.
Return entities whose name ends with this text (case-insensitive). Cannot be combined with ids, fullNames, nameFrom, nameTo.
Return entities whose name ends with this text (case-insensitive). Cannot be combined with ids, fullNames, nameFrom, nameTo.
Return entities whose name sorts at or after this value. Cannot be combined with ids, fullNames, nameStartsWith, nameContains, nameEndsWith.
Return entities whose name sorts at or after this value. Cannot be combined with ids, fullNames, nameStartsWith, nameContains, nameEndsWith.
Return entities whose name sorts at or before this value. Cannot be combined with ids, fullNames, nameStartsWith, nameContains, nameEndsWith.
Return entities whose name sorts at or before this value. Cannot be combined with ids, fullNames, nameStartsWith, nameContains, nameEndsWith.
Cursor from the previous page’s nextCursor. Send it with no other filters to fetch the next page.
Cursor from the previous page’s nextCursor. Send it with no other filters to fetch the next page.
Responses
Section titled “Responses”A list of entities.
object
Always list.
The endpoint that produced this list.
Objects on this page.
Customer as stored in QuickBooks Desktop.
object
QuickBooks-assigned ID of this customer.
Type of this object.
When this customer was created, as an ISO 8601 date-time with the QuickBooks computer’s UTC offset.
When this customer 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 customer. 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 customer, unique within its parent level.
Full hierarchical name of this customer: parent names and its own name separated by colons.
Whether this customer 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.
Company name.
Salutation such as Mr. or Dr.
First name.
Middle name or initial.
Last name.
Job title.
Address as stored in QuickBooks Desktop.
object
First address line.
Second address line.
Third address line.
Fourth address line.
Fifth address line.
City or locality.
State, province or region.
Postal or ZIP code.
Country.
Note for this address.
Address as stored in QuickBooks Desktop.
object
First address line.
Second address line.
Third address line.
Fourth address line.
Fifth address line.
City or locality.
State, province or region.
Postal or ZIP code.
Country.
Note for this address.
Ship to address as stored in QuickBooks Desktop.
object
Name of this ship to address, unique within its parent level.
First address line.
Second address line.
Third address line.
Fourth address line.
Fifth address line.
City or locality.
State, province or region.
Postal or ZIP code.
Country.
Note for this ship to address.
Whether this ship to address is default shipping address.
Main phone number.
Alternate phone number.
Fax number.
Email address.
Email address copied on emailed forms.
Name of the main contact person.
Name of an alternate contact person.
Custom contact fields entries for this customer.
Additional contact ref as stored in QuickBooks Desktop.
object
Name of this additional contact ref, unique within its parent level.
Value.
Additional contacts entries for this customer.
Contacts as stored in QuickBooks Desktop.
object
QuickBooks-assigned ID of this contacts.
Type of this object.
When this contacts was created, as an ISO 8601 date-time with the QuickBooks computer’s UTC offset.
When this contacts 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 contacts. 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 contacts, unique within its parent level.
Salutation such as Mr. or Dr.
First name.
Middle name or initial.
Last name.
Job title.
Custom contact fields entries for this contacts.
Additional contact ref as stored in QuickBooks Desktop.
object
Name of this additional contact ref, unique within its parent level.
Value.
Open balance of this customer alone, as a decimal string.
Open balance including all child jobs, as a decimal string.
Resale number of this customer.
Account number for this customer.
Credit limit as a decimal string.
Credit card info as stored in QuickBooks Desktop.
object
Number of this credit card info.
Expiration month of this credit card info.
Expiration year of this credit card info.
Name of this credit card info, unique within its parent level.
Address of this credit card info.
Postal or ZIP code.
Job status of this customer.
Job start date (YYYY-MM-DD).
Job projected end date (YYYY-MM-DD).
Job end date (YYYY-MM-DD).
Job description of this customer.
Note for this customer.
Additional notes entries for this customer.
Additional notes as stored in QuickBooks Desktop.
object
QuickBooks-assigned ID of this additional notes.
Date (YYYY-MM-DD).
Note for this additional notes.
Preferred delivery method of this customer.
Your own UUID for this customer, stored by QuickBooks so you can match records with your system.
Custom field values QuickBooks stores on this customer.
Custom field as stored in QuickBooks Desktop.
object
Owner of the custom field: “0” for public fields shown in the QuickBooks UI.
Name of this custom field, unique within its parent level.
Type.
Value.
Employee as stored in QuickBooks Desktop.
object
QuickBooks-assigned ID of this employee.
Type of this object.
When this employee was created, as an ISO 8601 date-time with the QuickBooks computer’s UTC offset.
When this employee 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 employee. 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 employee, unique within its parent level.
Whether this employee is active. Inactive objects stay in QuickBooks but are hidden from most lists.
Salutation such as Mr. or Dr.
First name.
Middle name or initial.
Last name.
Job title.
Department of this employee.
Description of this employee.
Target bonus of this employee. Decimal string with up to 2 decimal places.
Employee address as stored in QuickBooks Desktop.
object
First address line.
Second address line.
City or locality.
State, province or region.
Postal or ZIP code.
Print as of this employee.
Main phone number.
Mobile of this employee.
Pager of this employee.
Pager pin of this employee.
Alternate phone number.
Fax number.
Ssn of this employee.
Email address.
Custom contact fields entries for this employee.
Additional contact ref as stored in QuickBooks Desktop.
object
Name of this additional contact ref, unique within its parent level.
Value.
Emergency contacts as stored in QuickBooks Desktop.
object
Employee type of this employee.
Employment status of this employee.
Overtime exempt status of this employee.
Key employee status of this employee.
Gender of this employee.
Hired date (YYYY-MM-DD).
Original hire date (YYYY-MM-DD).
Adjusted service date (YYYY-MM-DD).
Termination date (YYYY-MM-DD).
Birth date (YYYY-MM-DD).
Us citizenship status of this employee.
Ethnicity of this employee.
Disability status of this employee.
Disability description of this employee.
I9 on file status of this employee.
Work authorization expiration date (YYYY-MM-DD).
Us veteran status of this employee.
Military status of this employee.
Account number for this employee.
Note for this employee.
Additional notes entries for this employee.
Additional notes as stored in QuickBooks Desktop.
object
QuickBooks-assigned ID of this additional notes.
Date (YYYY-MM-DD).
Note for this additional notes.
Employee payroll info as stored in QuickBooks Desktop.
object
Pay period of this employee payroll info.
Delete all earnings of this employee payroll info.
Earnings entries for this employee payroll info.
Earnings as stored in QuickBooks Desktop.
object
Price per unit, as a decimal string.
Price as a percentage, for percentage-based items. Percentage as a decimal string: “7.5” means 7.5 %.
Use time data to create paychecks of this employee payroll info.
Sick hours as stored in QuickBooks Desktop.
object
Hours available of this sick hours.
Accrual period of this sick hours.
Hours accrued per period of this sick hours.
Maximum hours of this sick hours.
Whether resets hours each year.
Hours used of this sick hours.
Accrual start date (YYYY-MM-DD).
Vacation hours as stored in QuickBooks Desktop.
object
Hours available of this vacation hours.
Accrual period of this vacation hours.
Hours accrued per period of this vacation hours.
Maximum hours of this vacation hours.
Whether resets hours each year.
Hours used of this vacation hours.
Accrual start date (YYYY-MM-DD).
Your own UUID for this employee, stored by QuickBooks so you can match records with your system.
Custom field values QuickBooks stores on this employee.
Custom field as stored in QuickBooks Desktop.
object
Owner of the custom field: “0” for public fields shown in the QuickBooks UI.
Name of this custom field, unique within its parent level.
Type.
Value.
Other name as stored in QuickBooks Desktop.
object
QuickBooks-assigned ID of this other name.
Type of this object.
When this other name was created, as an ISO 8601 date-time with the QuickBooks computer’s UTC offset.
When this other name 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 other name. 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 other name, unique within its parent level.
Whether this other name is active. Inactive objects stay in QuickBooks but are hidden from most lists.
Company name.
Salutation such as Mr. or Dr.
First name.
Middle name or initial.
Last name.
Address as stored in QuickBooks Desktop.
object
First address line.
Second address line.
Third address line.
Fourth address line.
Fifth address line.
City or locality.
State, province or region.
Postal or ZIP code.
Country.
Note for this address.
Main phone number.
Alternate phone number.
Fax number.
Email address.
Name of the main contact person.
Name of an alternate contact person.
Account number for this other name.
Note for this other name.
Your own UUID for this other name, stored by QuickBooks so you can match records with your system.
Custom field values QuickBooks stores on this other name.
Custom field as stored in QuickBooks Desktop.
object
Owner of the custom field: “0” for public fields shown in the QuickBooks UI.
Name of this custom field, unique within its parent level.
Type.
Value.
Vendor as stored in QuickBooks Desktop.
object
QuickBooks-assigned ID of this vendor.
Type of this object.
When this vendor was created, as an ISO 8601 date-time with the QuickBooks computer’s UTC offset.
When this vendor 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 vendor. 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 vendor, unique within its parent level.
Whether this vendor is active. Inactive objects stay in QuickBooks but are hidden from most lists.
Company name.
Salutation such as Mr. or Dr.
First name.
Middle name or initial.
Last name.
Job title.
Address as stored in QuickBooks Desktop.
object
First address line.
Second address line.
Third address line.
Fourth address line.
Fifth address line.
City or locality.
State, province or region.
Postal or ZIP code.
Country.
Note for this address.
Address as stored in QuickBooks Desktop.
object
First address line.
Second address line.
Third address line.
Fourth address line.
Fifth address line.
City or locality.
State, province or region.
Postal or ZIP code.
Country.
Note for this address.
Main phone number.
Alternate phone number.
Fax number.
Email address.
Email address copied on emailed forms.
Name of the main contact person.
Name of an alternate contact person.
Custom contact fields entries for this vendor.
Additional contact ref as stored in QuickBooks Desktop.
object
Name of this additional contact ref, unique within its parent level.
Value.
Additional contacts entries for this vendor.
Contacts as stored in QuickBooks Desktop.
object
QuickBooks-assigned ID of this contacts.
Type of this object.
When this contacts was created, as an ISO 8601 date-time with the QuickBooks computer’s UTC offset.
When this contacts 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 contacts. 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 contacts, unique within its parent level.
Salutation such as Mr. or Dr.
First name.
Middle name or initial.
Last name.
Job title.
Custom contact fields entries for this contacts.
Additional contact ref as stored in QuickBooks Desktop.
object
Name of this additional contact ref, unique within its parent level.
Value.
Name on check of this vendor.
Account number for this vendor.
Note for this vendor.
Additional notes entries for this vendor.
Additional notes as stored in QuickBooks Desktop.
object
QuickBooks-assigned ID of this additional notes.
Date (YYYY-MM-DD).
Note for this additional notes.
Credit limit as a decimal string.
Tax identification number of this vendor.
Whether this vendor is eligible for1099.
Open balance of this vendor alone, as a decimal string.
Your own UUID for this vendor, stored by QuickBooks so you can match records with your system.
The default expense accounts for this vendor.
object
QuickBooks ID of the referenced object.
Full name of the referenced object at the time of the response.
Custom field values QuickBooks stores on this vendor.
Custom field as stored in QuickBooks Desktop.
object
Owner of the custom field: “0” for public fields shown in the QuickBooks UI.
Name of this custom field, unique within its parent level.
Type.
Value.
A entity of a kind QuickBooks returned that this API version does not model yet, kept with its identity and raw fields.
object
QuickBooks ID of the entity (ListID or TxnID).
Always qbd_unrecognized_entity: a kind of entity this API version does not model yet.
The qbXML element QuickBooks returned, such as ItemServiceRet; it names the kind.
When it was created, as an ISO 8601 date-time.
When it was last changed, as an ISO 8601 date-time.
Current revision (EditSequence).
Name, when QuickBooks returned one.
Full name, when QuickBooks returned one.
Whether it is active, when QuickBooks returned it.
Every element QuickBooks returned, by qbXML element name: text values as strings, nested elements as objects, repeated ones as arrays.
object
Cursor for the next page, or null on the last page.
Whether more pages remain.
Records left after this page, as reported by QuickBooks.
Estimated deadline for requesting the next page (UTC).
Example
{ "objectType": "list", "url": "/v1/quickbooks-desktop/entities", "data": [ { "objectType": "qbd_customer", "createdAt": "2026-10-05T09:14:03-07:00", "updatedAt": "2026-10-05T09:14:03-07:00", "additionalContacts": [ { "objectType": "qbd_contact", "createdAt": "2026-10-05T09:14:03-07:00", "updatedAt": "2026-10-05T09:14:03-07:00" } ], "balance": "1250.00", "totalBalance": "1250.00", "creditLimit": "1250.00", "jobStatus": "awarded", "jobStartDate": "2026-10-05", "jobProjectedEndDate": "2026-10-05", "jobEndDate": "2026-10-05", "additionalNotes": [ { "date": "2026-10-05" } ], "preferredDeliveryMethod": "none", "customFields": [ { "type": "amount_type" } ] } ]}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, CURSOR_INVALID, CURSOR_PARAMS_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
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": {} }}400 CURSOR_INVALID
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "CURSOR_INVALID", "message": "The cursor is malformed, out of date or belongs to another end user.", "userFacingMessage": "This action could not be completed. Please contact the application provider.", "httpStatusCode": 400, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "Only the most recent cursor of a list can be used, and only for the end user and query that produced it. Every page returns a new cursor; resending one repeats its page at most twice.", "fixes": [ { "actor": "developer", "action": "Use the nextCursor from the latest page, or start the list again without a cursor." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#cursor_invalid", "retryable": false, "outcome": "not_applicable", "param": null, "details": {} }}400 CURSOR_PARAMS_MISMATCH
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "CURSOR_PARAMS_MISMATCH", "message": "Filter parameters cannot change while paging with a cursor.", "userFacingMessage": "This action could not be completed. Please contact the application provider.", "httpStatusCode": 400, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "Filters are fixed when a list starts and the cursor remembers them. A continue request may resend exactly the same filters; a changed, added or dropped filter would describe a different list.", "fixes": [ { "actor": "developer", "action": "Send cursor (and optionally limit) alone, or with exactly the filters of the first request. To change a filter, start the list again without a cursor." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#cursor_params_mismatch", "retryable": false, "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 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.
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, 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 cursor expired. Codes: CURSOR_EXPIRED.
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
410 CURSOR_EXPIRED
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "CURSOR_EXPIRED", "message": "The cursor expired (idle_timeout) after 3 page(s) and 450 record(s).", "userFacingMessage": "The list took too long to load and has to start again. Please try again.", "httpStatusCode": 410, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "A cursor lives only as long as the QuickBooks session that holds its query. `details.reason` says why it ended.", "fixes": [ { "actor": "developer", "action": "Restart the list with an updatedAfter watermark from the last record you processed." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#cursor_expired", "retryable": false, "outcome": "not_applicable", "param": null, "details": { "reason": "idle_timeout", "pagesServed": 3, "recordsServed": 450 } }}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, QBD_RESPONSE_TOO_LARGE.
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": {} }}422 QBD_RESPONSE_TOO_LARGE
{ "error": { "type": "INTEGRATION_ERROR", "code": "QBD_RESPONSE_TOO_LARGE", "message": "The QuickBooks response is larger than the API returns in one call.", "userFacingMessage": "QuickBooks Desktop returned more data than can be loaded at once. Please contact the application provider.", "httpStatusCode": 422, "integrationCode": null, "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "cause": "The query matched more data than fits in one response.", "fixes": [ { "actor": "developer", "action": "Narrow the filters or use a paginated list." } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_response_too_large", "retryable": false, "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.
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.
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": {} }}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.