Retrieve a request
Try itGET /v1/requests/{id}
Sends a real request to the API from your browser. A test key (sk_test_) is recommended.
Query parameters (1 optional)
const url = 'https://api.desktopaccountingapi.com/v1/requests/req_01j9x4m6v4c8k2t7q0r5s3w1zd?waitSeconds=0';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.desktopaccountingapi.com/v1/requests/req_01j9x4m6v4c8k2t7q0r5s3w1zd?waitSeconds=0' \ --header 'Authorization: Bearer <token>'Returns a QuickBooks-bound request with its status, queue position, timeline, diagnosis, native status and result. With waitSeconds, the call waits up to that long for the request to finish (or become outcome_unknown) before answering. Use it after 504 QBD_REQUEST_TIMEOUT or a 202 async response to collect the result without resending. A call that was rejected before it was queued (for example INTEGRATION_CONNECTION_NOT_SET_UP, a validation error or a disabled connection) is retrievable under the request ID its error returned, as a failed request with sentAt: null, the catalog error for its code and no result, when it named an end user of this project that has a connection.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Unique identifier for the request.
Example
req_01j9x4m6v4c8k2t7q0r5s3w1zdUnique identifier for the request.
Query Parameters
Section titled “Query Parameters”Seconds to wait for a final status, 0–60. Default 0.
Example
30Seconds to wait for a final status, 0–60. Default 0.
Responses
Section titled “Responses”The request.
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). 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") and values the API read leniently from a damaged company file. 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.
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. null for codes that appear only on a request resource (REQUEST_EXPIRED, REQUEST_CANCELED).
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": "INVALID_REQUEST_ERROR", "code": "INVALID_JSON", "httpStatusCode": 503, "integrationCode": "0x80040414", "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "fixes": [ { "actor": "developer" } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_modal_dialog_open", "outcome": "applied", "param": "companyName" }}Headers
Section titled “Headers”Unique ID of this API call (req_...). Present on every response.
Requests allowed per window for the project (all keys together).
Requests left in the current window, as counted by the edge location that served this call.
Seconds until the current window resets.
The request is invalid. Codes: UNKNOWN_HEADER, INVALID_PARAMETER.
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. null for codes that appear only on a request resource (REQUEST_EXPIRED, REQUEST_CANCELED).
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
Example
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "INVALID_JSON", "httpStatusCode": 503, "integrationCode": "0x80040414", "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "fixes": [ { "actor": "developer" } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_modal_dialog_open", "outcome": "applied", "param": "companyName" }}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. null for codes that appear only on a request resource (REQUEST_EXPIRED, REQUEST_CANCELED).
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
Example
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "INVALID_JSON", "httpStatusCode": 503, "integrationCode": "0x80040414", "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "fixes": [ { "actor": "developer" } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_modal_dialog_open", "outcome": "applied", "param": "companyName" }}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. null for codes that appear only on a request resource (REQUEST_EXPIRED, REQUEST_CANCELED).
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
Example
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "INVALID_JSON", "httpStatusCode": 503, "integrationCode": "0x80040414", "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "fixes": [ { "actor": "developer" } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_modal_dialog_open", "outcome": "applied", "param": "companyName" }}Headers
Section titled “Headers”Unique ID of this API call (req_...). Present on every response.
Requests allowed per window for the project (all keys together).
Requests left in the current window, as counted by the edge location that served this call.
Seconds until the current window resets.
true when repeating the identical request can succeed. SDKs follow it instead of status-code heuristics.
Seconds to wait before retrying, on 429 and on retryable 503 responses when a wait is known.
Too many requests. Codes: RATE_LIMITED.
object
object
Error category. Use it to choose between retrying, fixing the request and asking the end user to act.
Stable error code from the error catalog. New codes may be added; a code’s meaning never changes.
Developer-facing explanation. May include IDs and field paths; never includes secrets.
A message that is safe to show to the end user.
HTTP status of the response. null for codes that appear only on a request resource (REQUEST_EXPIRED, REQUEST_CANCELED).
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
Example
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "INVALID_JSON", "httpStatusCode": 503, "integrationCode": "0x80040414", "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "fixes": [ { "actor": "developer" } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_modal_dialog_open", "outcome": "applied", "param": "companyName" }}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. null for codes that appear only on a request resource (REQUEST_EXPIRED, REQUEST_CANCELED).
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
Example
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "INVALID_JSON", "httpStatusCode": 503, "integrationCode": "0x80040414", "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "fixes": [ { "actor": "developer" } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_modal_dialog_open", "outcome": "applied", "param": "companyName" }}Headers
Section titled “Headers”Unique ID of this API call (req_...). Present on every response.
Requests allowed per window for the project (all keys together).
Requests left in the current window, as counted by the edge location that served this call.
Seconds until the current window resets.
true when repeating the identical request can succeed. SDKs follow it instead of status-code heuristics.
Seconds to wait before retrying, on 429 and on retryable 503 responses when a wait is known.
QuickBooks Desktop or the service is not available. Codes: SERVICE_UNAVAILABLE.
object
object
Error category. Use it to choose between retrying, fixing the request and asking the end user to act.
Stable error code from the error catalog. New codes may be added; a code’s meaning never changes.
Developer-facing explanation. May include IDs and field paths; never includes secrets.
A message that is safe to show to the end user.
HTTP status of the response. null for codes that appear only on a request resource (REQUEST_EXPIRED, REQUEST_CANCELED).
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
Example
{ "error": { "type": "INVALID_REQUEST_ERROR", "code": "INVALID_JSON", "httpStatusCode": 503, "integrationCode": "0x80040414", "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zd", "fixes": [ { "actor": "developer" } ], "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_modal_dialog_open", "outcome": "applied", "param": "companyName" }}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.