# Error codes
Source: https://www.desktopaccountingapi.com/docs/errors/

> Every error code the Desktop Accounting API returns, with its HTTP status, cause, fixes, retry rule and an example body.

Every error response has the same shape, and every `code` below is stable: its meaning never changes, and new codes only get added. The `docsUrl` field in an error body links straight to the matching section on this page.

```json
{
  "error": {
    "type": "INTEGRATION_CONNECTION_ERROR",
    "code": "QBD_MODAL_DIALOG_OPEN",
    "message": "QuickBooks Desktop has a dialog window open, so it could not accept the request.",
    "userFacingMessage": "QuickBooks Desktop has a window open that needs attention. Close any open QuickBooks dialog on the computer that runs QuickBooks, then try again.",
    "httpStatusCode": 503,
    "integrationCode": "0x80040414",
    "requestId": "req_01j9x4m6v4c8k2t7q0r5s3w1zb",
    "cause": "A modal dialog blocks every integrated application until someone closes it.",
    "fixes": [{ "actor": "end_user", "action": "Close the open dialog in QuickBooks Desktop on the host computer." }],
    "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_modal_dialog_open",
    "retryable": true,
    "outcome": "not_applied",
    "param": null,
    "details": {}
  }
}
```

Read [Error handling](https://www.desktopaccountingapi.com/docs/guides/error-handling/) for what each field means and how to route errors in your code. The short version:

- Branch on `code`, not on `message`. Messages can get more specific over time.
- Show `userFacingMessage` to your customer. It never contains keys, billing details or internal identifiers.
- Retry only when `retryable` is `true` (also sent as the `Daapi-Should-Retry` header). Never resend a write whose `outcome` is `unknown` or `pending`.
- Quote `requestId` when you contact support. The dashboard request log opens it directly.

This page is generated from the same error catalog the API uses at runtime, so it always matches the codes the API sends. The catalog is also published as JSON at [/docs/errors.json](https://www.desktopaccountingapi.com/docs/errors.json), with every code, retry rule, cause, fix, documented `details` key, the qbXML status mapping and the [diagnosis causes](https://www.desktopaccountingapi.com/docs/troubleshooting/), for tools and SDKs.

66 codes in 9 types.

## Retry guidance

Every code carries one of four retry rules:

- **Retry the same request** (`retry_same_request`). Repeating the identical request (same Idempotency-Key for writes) can succeed. SDKs retry it automatically with backoff.
- **Read the request instead of resending** (`poll_request`). The request keeps running. Poll GET /v1/requests/{id}?waitSeconds=60; never resend it.
- **Never resend; check QuickBooks first** (`never_resend_check_first`). Never resend automatically. Check in QuickBooks whether the change exists before trying again.
- **Change the request or the setup first** (`change_request_or_environment`). Repeating the same request fails the same way. Change the request, or have the end user or developer apply a fix first.

## Invalid request error (`INVALID_REQUEST_ERROR`)

The request is invalid. Fix it before sending it again.

### INVALID_JSON

- HTTP status: 400
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** The request body is not valid JSON.

**Cause.** The body could not be parsed as JSON, or the Content-Type header does not match the body.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Send a UTF-8 JSON body with Content-Type: application/json.

### INVALID_PARAMETER

- HTTP status: 400
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** A request parameter is invalid.

**Cause.** A field, query parameter or header failed validation. `param` names the field.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Correct the field named in `param` using the constraints in the API reference.

Guide: [Data conventions](https://www.desktopaccountingapi.com/docs/quickbooks/conventions/).

### UNKNOWN_PARAMETER

- HTTP status: 400
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** The request contains a field this operation does not accept.

**Cause.** Request bodies are strict. A misspelled or unsupported field is rejected instead of being ignored.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Remove or rename the field named in `param`.

Guide: [Data conventions](https://www.desktopaccountingapi.com/docs/quickbooks/conventions/).

### UNKNOWN_HEADER

- HTTP status: 400
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** The request contains an unknown Daapi-* header.

**Cause.** Unknown Daapi-* headers are rejected so that a typo does not silently fall back to a default.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Check the header name named in `param` against the header reference.

Guide: [Using the API](https://www.desktopaccountingapi.com/docs/api/).

### DECIMAL_PRECISION_EXCEEDED

- HTTP status: 400
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** A decimal value has more decimal places than QuickBooks stores for this field.

**Cause.** QuickBooks stores amounts with 2 decimal places and prices and quantities with 5. Values are never rounded silently.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Round the value named in `param` before sending it.

Guide: [Data conventions](https://www.desktopaccountingapi.com/docs/quickbooks/conventions/).

### STRING_TOO_LONG

- HTTP status: 400
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** A text value is longer than QuickBooks allows for this field.

**Cause.** Each QuickBooks text field has a maximum length.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Shorten the value named in `param` to the documented maximum length.

Guide: [Data conventions](https://www.desktopaccountingapi.com/docs/quickbooks/conventions/).

### UNSUPPORTED_CHARACTER

- HTTP status: 400
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** A text value contains a character QuickBooks cannot store.

**Cause.** US editions of QuickBooks Desktop store text in the Windows-1252 code page. Characters outside it (emoji, Greek or Asian scripts, fullwidth forms such as ＆, control characters) are rejected rather than silently changed. Accented Latin letters, €, µ, the no-break space, curly quotes and dashes are stored as sent; decomposed accents are normalized to their composed form first.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Replace the character reported in `details` in the field named in `param`; `details.suggestion` names a replacement when there is an obvious one.

**Details**

- `details.codePoint`: Unicode code point of the first rejected character.
- `details.character`: The character itself, or null for control characters.
- `details.index`: Its position in the value (0-based, in characters).
- `details.suggestion`: A replacement QuickBooks can store, or null.

Guide: [Data conventions](https://www.desktopaccountingapi.com/docs/quickbooks/conventions/).

### FIELD_NOT_CLEARABLE

- HTTP status: 400
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** This field cannot be cleared with null.

**Cause.** QuickBooks only supports clearing some fields. Fields that support it are marked x-daapi-clearable in the reference.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Omit the field to leave it unchanged, or send a replacement value.

Guide: [Updates and line items](https://www.desktopaccountingapi.com/docs/quickbooks/updates-and-line-items/).

### END_USER_ID_MISSING

- HTTP status: 400
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** QuickBooks Desktop operations require the Daapi-End-User-Id header.

**Cause.** The request did not say which end user, and therefore which QuickBooks company file, it is for.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Send Daapi-End-User-Id with the end user's ID (eu_...).

Guide: [Authentication](https://www.desktopaccountingapi.com/docs/get-started/authentication/).

### PAYLOAD_TOO_LARGE

- HTTP status: 413
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** The request body is larger than 20 MiB.

**Cause.** Request bodies are capped at 20 MiB.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Split the work into several smaller requests.

Guide: [Using the API](https://www.desktopaccountingapi.com/docs/api/).

### IDEMPOTENCY_KEY_INVALID

- HTTP status: 400
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** The Idempotency-Key header must be 1–255 printable ASCII characters.

**Cause.** The Idempotency-Key value is empty, too long or contains characters outside printable ASCII.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Use a UUID or another value of 1–255 printable ASCII characters.

Guide: [Idempotency and safe retries](https://www.desktopaccountingapi.com/docs/guides/idempotency/).

### IDEMPOTENCY_KEY_REUSED

- HTTP status: 422
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** This Idempotency-Key was already used with a different request.

**Cause.** A key identifies one logical request. The method, path, end user or body differs from the first use of this key.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Generate a new key for each logical request and reuse it only for retries of that request.

Guide: [Idempotency and safe retries](https://www.desktopaccountingapi.com/docs/guides/idempotency/).

### CURSOR_INVALID

- HTTP status: 400
- Retry: Change the request or the setup first
- Outcome: `not_applicable`

**Message.** The cursor is malformed, out of date or belongs to another end user.

**Cause.** Only the most recent cursor of a list can be used, and only for the end user and query that produced it. Every page returns a new cursor; resending one repeats its page at most twice.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Use the nextCursor from the latest page, or start the list again without a cursor.

Guide: [Pagination](https://www.desktopaccountingapi.com/docs/guides/pagination/).

### CURSOR_PARAMS_MISMATCH

- HTTP status: 400
- Retry: Change the request or the setup first
- Outcome: `not_applicable`

**Message.** Filter parameters cannot change while paging with a cursor.

**Cause.** Filters are fixed when a list starts and the cursor remembers them. A continue request may resend exactly the same filters; a changed, added or dropped filter would describe a different list.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Send cursor (and optionally limit) alone, or with exactly the filters of the first request. To change a filter, start the list again without a cursor.

Guide: [Pagination](https://www.desktopaccountingapi.com/docs/guides/pagination/).

### CURSOR_EXPIRED

- HTTP status: 410
- Retry: Change the request or the setup first
- Outcome: `not_applicable`

**Message.** The cursor expired because QuickBooks discarded the underlying query.

**Cause.** A cursor lives only as long as the QuickBooks session that holds its query. `details.reason` says why it ended.

**What the end user sees.** Something went wrong while contacting QuickBooks. Please try again in a moment.

**How to fix it**

- You (developer): Restart the list with an updatedAfter watermark from the last record you processed.

**Details**

- `details.reason`: `idle_timeout`, `session_ended`, `quickbooks_restarted` or `evicted`.
- `details.pagesServed`: Pages returned before the cursor expired.
- `details.recordsServed`: Records returned before the cursor expired.

Guide: [Pagination](https://www.desktopaccountingapi.com/docs/guides/pagination/).

### RESOURCE_MISSING

- HTTP status: 404
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** No such object exists in this project.

**Cause.** The ID does not exist, was deleted, or belongs to another project.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Check the ID and that the secret key belongs to the project that owns the object.

### REQUEST_NOT_CANCELABLE

- HTTP status: 409
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** The request was already sent to QuickBooks and cannot be canceled.

**Cause.** Cancellation is possible only before a request is handed to the Web Connector.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Wait for the request to finish with GET /v1/requests/{id}.

Guide: [Request lifecycle](https://www.desktopaccountingapi.com/docs/guides/request-lifecycle/).

### PASSTHROUGH_INVALID_QBXML

- HTTP status: 400
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** The passthrough body cannot be converted to a valid qbXML message set.

**Cause.** Passthrough accepts qbXML request elements (names ending in Rq) as JSON or as a QBXMLMsgsRq XML fragment.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Send one or more request elements such as CustomerQueryRq; see `details` for the position of the problem.

Guide: [Passthrough and raw qbXML](https://www.desktopaccountingapi.com/docs/quickbooks/passthrough/).

### QBD_FIELD_UNSUPPORTED_BY_VERSION

- HTTP status: 422
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** The connected QuickBooks version does not support this field or operation.

**Cause.** The field or operation was introduced in a newer qbXML version than the connected QuickBooks supports. `details.minimumQbxmlVersion` gives the version needed.

**What the end user sees.** This feature needs a newer version of QuickBooks Desktop. Please contact the application provider.

**How to fix it**

- You (developer): Omit the field for this end user, or check the connection's qbxmlVersion before sending it.
- End user: Update QuickBooks Desktop to a release that supports the feature.

**Details**

- `details.minimumQbxmlVersion`: qbXML version that introduced the field or operation.
- `details.qbxmlVersion`: qbXML version of the connected QuickBooks.

Guide: [Editions, versions and features](https://www.desktopaccountingapi.com/docs/quickbooks/editions-and-features/).

### QBD_REGION_UNSUPPORTED

- HTTP status: 422
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** The connected QuickBooks Desktop is not a US edition.

**Cause.** Desktop Accounting API supports US editions of QuickBooks Desktop. Canadian, UK and Australian editions use different schemas.

**What the end user sees.** This version of QuickBooks Desktop is not supported. Only US editions can be connected.

**How to fix it**

- You (developer): Use passthrough for non-US editions at your own risk, or connect a US edition.

**Details**

- `details.country`: Country code QuickBooks reported for the company file.

Guide: [Supported environments](https://www.desktopaccountingapi.com/docs/platform/supported-environments/). End-user help: [This QuickBooks version is not supported](https://www.desktopaccountingapi.com/docs/help/connection-errors/quickbooks-version-unsupported/).

### WEBHOOK_ENDPOINT_LIMIT_REACHED

- HTTP status: 422
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** This project already has the maximum number of webhook endpoints.

**Cause.** A project can register up to 20 webhook endpoints.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Delete an endpoint you no longer use, or subscribe one endpoint to more event types.

**Details**

- `details.limit`: Maximum endpoints per project.

Guide: [Webhooks](https://www.desktopaccountingapi.com/docs/guides/webhooks/).

### QBD_OPERATION_UNSUPPORTED

- HTTP status: 422
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** QuickBooks Desktop offers no way to perform this operation through its integration interface.

**Cause.** This is a documented incompatibility: the QuickBooks Desktop SDK (qbXML) has no request for this operation, so no integration can perform it. `details.alternatives` lists what to do instead.

**What the end user sees.** This action is not available for QuickBooks Desktop. Please contact the application provider.

**How to fix it**

- You (developer): Use one of the alternatives in details.alternatives, for example deleting the transaction instead of voiding it.
- End user: Perform the action in the QuickBooks Desktop window.

**Details**

- `details.operationId`: The unsupported operation.
- `details.alternatives`: What to do instead.

Guide: [Supported environments](https://www.desktopaccountingapi.com/docs/platform/supported-environments/).

### REQUEST_CANCELED

- HTTP status: none (appears only on a request resource)
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** The request was canceled before it was sent to QuickBooks.

**Cause.** The request was canceled by the caller before the Web Connector picked it up.

**What the end user sees.** The request was canceled.

**How to fix it**

- You (developer): Submit a new request if the work is still needed.

Guide: [Request lifecycle](https://www.desktopaccountingapi.com/docs/guides/request-lifecycle/).

## Authentication error (`AUTHENTICATION_ERROR`)

The API key is missing or invalid.

### API_KEY_MISSING

- HTTP status: 401
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** No API key was provided. Send Authorization: Bearer <secret key>.

**Cause.** The Authorization header is missing or is not a Bearer token.

**What the end user sees.** This application could not connect to QuickBooks right now. Please contact the application provider.

**How to fix it**

- You (developer): Send Authorization: Bearer sk_live_... (or sk_test_...) from your server.

Guide: [Authentication](https://www.desktopaccountingapi.com/docs/get-started/authentication/).

### API_KEY_INVALID

- HTTP status: 401
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** The API key is invalid or has been revoked.

**Cause.** The key is malformed, unknown, or was revoked. Revocation takes effect within 30 seconds.

**What the end user sees.** This application could not connect to QuickBooks right now. Please contact the application provider.

**How to fix it**

- You (developer): Create a new secret key in the dashboard and update your server configuration.

Guide: [Authentication](https://www.desktopaccountingapi.com/docs/get-started/authentication/).

### PUBLISHABLE_KEY_INVALID

- HTTP status: 401
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** The publishable key is not valid.

**Cause.** The publishableKey is malformed, unknown or was rotated.

**What the end user sees.** This application could not connect to QuickBooks right now. Please contact the application provider.

**How to fix it**

- You (developer): Copy the current publishable key from the project's API keys page.

Guide: [Authentication](https://www.desktopaccountingapi.com/docs/get-started/authentication/).

## Permission error (`PERMISSION_ERROR`)

The project may not perform this operation.

### PUBLISHABLE_KEY_PROJECT_MISMATCH

- HTTP status: 403
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** The publishable key belongs to a different project than the secret key.

**Cause.** Auth sessions must be created with a publishable key and a secret key from the same project.

**What the end user sees.** This application could not connect to QuickBooks right now. Please contact the application provider.

**How to fix it**

- You (developer): Use the publishable key of the project that owns your secret key.

Guide: [Authentication](https://www.desktopaccountingapi.com/docs/get-started/authentication/).

### TEST_COMPANY_FILE_LIMIT_REACHED

- HTTP status: 403
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** Test projects in this organization already connect the maximum number of company files.

**Cause.** Test projects are free and limited to a small number of connected company files per organization. Reconnecting an end user to the same company file does not count again. A company file keeps counting for 30 days after a test connection last used it, also after its end user is deleted or its company file is reset. The connection checks the limit again whenever a test connection adopts a company file.

**What the end user sees.** This application cannot connect another QuickBooks company file right now. Please contact the application provider.

**How to fix it**

- You (developer): Connect the company file in a production project, or reuse a company file your test projects already connect. Files you stopped using free their slot 30 days after their last use.
- Support: Ask support to raise the limit for a legitimate test setup.

**Details**

- `details.used`: Company files connected across the organization test projects.
- `details.limit`: The organization limit.

Guide: [Test and production projects](https://www.desktopaccountingapi.com/docs/get-started/authentication/).

### API_KEY_READ_ONLY

- HTTP status: 403
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** This secret key is read-only and cannot change data.

**Cause.** The request was made with a read-only secret key. Read-only keys can call GET operations and passthrough requests that contain only queries (`...QueryRq`). Creating, updating, deleting or voiding objects, writes through passthrough, auth sessions, end-user changes, request cancellation and webhook endpoint changes need a full-access key. The API rejects the request before anything is queued or sent to QuickBooks.

**What the end user sees.** This application could not connect to QuickBooks right now. Please contact the application provider.

**How to fix it**

- You (developer): Use a full-access secret key for writes, or keep this key for read-only tools such as an MCP connection for AI agents.

### PERMISSION_DENIED

- HTTP status: 403
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** This project is not allowed to perform this operation.

**Cause.** The operation is not available for this project or object in its current state.

**What the end user sees.** This application could not connect to QuickBooks right now. Please contact the application provider.

**How to fix it**

- You (developer): Check the project and object state in the dashboard.

Guide: [End users and connections](https://www.desktopaccountingapi.com/docs/connect/end-users/).

## Billing error (`BILLING_ERROR`)

Billing pauses production data requests.

### BILLING_REQUIRED

- HTTP status: 402
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** Production data requests are paused because the organization has no active subscription.

**Cause.** The organization's 30-day production trial ended without a subscription, or its subscription ended. Health checks, auth sessions, end users, setup and test projects keep working.

**What the end user sees.** This application could not connect to QuickBooks right now. Please contact the application provider.

**How to fix it**

- You (developer): An organization owner starts a subscription on the dashboard's Billing page (`details.billingUrl`). Production requests work again within a minute.

Guide: [Billing and pricing](https://www.desktopaccountingapi.com/docs/platform/billing/).

### PAYMENT_FAILED

- HTTP status: 402
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** Production data requests are paused because payment failed.

**Cause.** The subscription has been past due for more than the 7-day grace period. Health checks, auth sessions, end users, setup and test projects keep working.

**What the end user sees.** This application could not connect to QuickBooks right now. Please contact the application provider.

**How to fix it**

- You (developer): An organization owner updates the payment method on the dashboard's Billing page (`details.billingUrl`, then Manage billing). Production requests work again once the payment succeeds.

Guide: [Billing and pricing](https://www.desktopaccountingapi.com/docs/platform/billing/).

## Rate limit error (`RATE_LIMIT_ERROR`)

Too many requests; retry after Retry-After.

### RATE_LIMITED

- HTTP status: 429
- Retry: Retry the same request
- Outcome: `not_applied`

**Message.** Too many requests for this project. Retry after the time in Retry-After.

**Cause.** The project exceeded its request rate across all keys, or too many requests (including ones with invalid keys) came from one IP address. `details.scope` says which limit applied.

**What the end user sees.** Something went wrong while contacting QuickBooks. Please try again in a moment.

**How to fix it**

- You (developer): Retry after the Retry-After interval and spread requests over time. Read the RateLimit-* headers to stay under the limit.

**Details**

- `details.scope`: `project` (requests per project across all keys) or `ip` (requests or failed authentications from one IP address).
- `details.limit`: Requests allowed per window.
- `details.windowSeconds`: Window length in seconds.

Guide: [Rate limits](https://www.desktopaccountingapi.com/docs/guides/rate-limits/).

### CONNECTION_QUEUE_FULL

- HTTP status: 429
- Retry: Retry the same request
- Outcome: `not_applied`

**Message.** This connection has too many pending requests.

**Cause.** QuickBooks processes one request at a time per company file. The connection already has the maximum number of pending requests (200), or of callers waiting synchronously (50). `details.reason` says which.

**What the end user sees.** Something went wrong while contacting QuickBooks. Please try again in a moment.

**How to fix it**

- You (developer): Wait for pending requests to finish before submitting more.
- You (developer): Use async requests (Prefer: respond-async) for bulk work instead of many concurrent synchronous calls.

**Details**

- `details.reason`: `pending_requests` or `sync_waiters`.
- `details.limit`: The limit that applied.

Guide: [Rate limits](https://www.desktopaccountingapi.com/docs/guides/rate-limits/).

## Integration connection error (`INTEGRATION_CONNECTION_ERROR`)

The end user's environment (computer, Web Connector, QuickBooks) is not ready. Log as a warning; usually the end user must act.

### INTEGRATION_CONNECTION_NOT_SET_UP

- HTTP status: 409
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** This end user has not finished connecting QuickBooks Desktop.

**Cause.** No Web Connector has completed setup for this end user.

**What the end user sees.** QuickBooks Desktop is not connected yet. Finish the connection setup to continue.

**How to fix it**

- You (developer): Create an auth session and send the end user its authFlowUrl.

Guide: [Connect an end user](https://www.desktopaccountingapi.com/docs/connect/setup-flow/).

### INTEGRATION_CONNECTION_NOT_ACTIVE

- HTTP status: 503
- Retry: Retry the same request
- Outcome: `not_applied`

**Message.** The QuickBooks Web Connector for this end user has not checked in recently.

**Cause.** The computer is off, asleep or signed out, the Web Connector is closed, or Auto-Run is off.

**What the end user sees.** The computer that runs QuickBooks Desktop is not reachable. Make sure it is on, signed in, and that the QuickBooks Web Connector is running.

**How to fix it**

- End user: Turn on and sign in to the computer that runs QuickBooks, start the QuickBooks Web Connector and check Auto-Run for this application.
- You (developer): Retry after the end user confirms the Web Connector is running.

Guide: [Connection status and health checks](https://www.desktopaccountingapi.com/docs/connect/connection-status/). End-user help: [Connection not active](https://www.desktopaccountingapi.com/docs/help/connection-errors/connection-not-active/).

### INTEGRATION_CONNECTION_DISABLED

- HTTP status: 403
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** This connection is disabled.

**Cause.** The connection was disabled in the dashboard.

**What the end user sees.** This QuickBooks connection is turned off. Please contact the application provider.

**How to fix it**

- You (developer): Enable the connection in the dashboard, or create a new auth session.

Guide: [End users and connections](https://www.desktopaccountingapi.com/docs/connect/end-users/).

### QBD_CONNECTION_ERROR

- HTTP status: 503
- Retry: Retry the same request
- Outcome: `not_applied`

**Message.** The Web Connector could not open QuickBooks Desktop.

**Cause.** QuickBooks reported an error opening the connection that has no more specific mapping. `integrationCode` has the HRESULT.

**What the end user sees.** QuickBooks Desktop could not be opened on the computer that runs it. Make sure QuickBooks is installed and the company file opens normally.

**How to fix it**

- End user: Open QuickBooks Desktop and the company file on the host computer and close any open windows.
- Support: Look up the HRESULT in integrationCode.

End-user help: [Connection not active](https://www.desktopaccountingapi.com/docs/help/connection-errors/connection-not-active/).

### QBD_CANNOT_START

- HTTP status: 503
- Retry: Retry the same request
- Outcome: `not_applied`
- QuickBooks codes: `0x80040408`, `0x80040401`

**Message.** QuickBooks Desktop could not be started on the host computer.

**Cause.** The Web Connector tried to start QuickBooks and failed, often because it is not installed for the signed-in Windows user or another instance is starting.

**What the end user sees.** QuickBooks Desktop could not start. Open QuickBooks and your company file on the computer that runs it, then try again.

**How to fix it**

- End user: Open QuickBooks Desktop and the company file manually and leave it open.

End-user help: [QuickBooks could not be started](https://www.desktopaccountingapi.com/docs/help/connection-errors/cannot-start-quickbooks/).

### QBD_STARTING

- HTTP status: 503
- Retry: Retry the same request
- Outcome: `not_applied`
- QuickBooks codes: `0x80040424`, `0x8004042D`

**Message.** QuickBooks Desktop is still starting.

**Cause.** QuickBooks had not finished opening the company file when the Web Connector connected.

**What the end user sees.** QuickBooks Desktop is still opening. Please try again in a minute.

**How to fix it**

- You (developer): Retry after a short wait.

End-user help: [QuickBooks could not be started](https://www.desktopaccountingapi.com/docs/help/connection-errors/cannot-start-quickbooks/).

### QBD_MODAL_DIALOG_OPEN

- HTTP status: 503
- Retry: Retry the same request
- Outcome: `not_applied`
- QuickBooks codes: `0x80040414`, `QBWC1053`

**Message.** QuickBooks Desktop has a dialog window open, so it could not accept the request.

**Cause.** A modal dialog (for example a backup reminder or an update prompt) blocks every integrated application until someone closes it.

**What the end user sees.** QuickBooks Desktop has a window open that needs attention. Close any open QuickBooks dialog on the computer that runs QuickBooks, then try again.

**How to fix it**

- End user: Close the open dialog in QuickBooks Desktop on the host computer.
- You (developer): Retry after the end user confirms; reads can be retried automatically.

End-user help: [A QuickBooks window is blocking the connection](https://www.desktopaccountingapi.com/docs/help/connection-errors/modal-dialog-open/).

### QBD_QUICKBOOKS_NOT_RESPONDING

- HTTP status: 503
- Retry: Retry the same request
- Outcome: `not_applied`
- QuickBooks codes: `QBWC1053`, `QBWC1079`

**Message.** The Web Connector checked in, but QuickBooks Desktop did not answer it, so the request was not sent.

**Cause.** The Web Connector started a session and QuickBooks never answered. Most often a QuickBooks dialog is open: the Web Connector reports that (QBWC1053) only in its own window and retries. A company file restored from an older backup can also fail this way (QBWC1079). `details.diagnosis` ranks the probable causes.

**What the end user sees.** QuickBooks Desktop is not responding. Close any open QuickBooks window or dialog on the computer that runs QuickBooks, then try again.

**How to fix it**

- End user: On the computer that runs QuickBooks, close any open QuickBooks dialog or window (preferences, backup reminder, update prompt, login).
- End user: If the company file was restored from a backup, remove this application from the Web Connector and add it again.
- You (developer): Retry after the end user confirms, or use async requests so the work waits for QuickBooks.

**Details**

- `details.requestId`: The request that was not sent.
- `details.diagnosis`: Probable causes ranked by likelihood.

Guide: [Request diagnosis](https://www.desktopaccountingapi.com/docs/troubleshooting/). End-user help: [A QuickBooks window is blocking the connection](https://www.desktopaccountingapi.com/docs/help/connection-errors/modal-dialog-open/).

### QBD_WRONG_COMPANY_FILE_OPEN

- HTTP status: 503
- Retry: Retry the same request
- Outcome: `not_applied`
- QuickBooks codes: `0x8004040A`

**Message.** A different QuickBooks company file is open on the host computer.

**Cause.** QuickBooks opens one company file at a time per computer, and the open file is not the one this connection uses.

**What the end user sees.** A different company file is open in QuickBooks Desktop. Open the company file you connected, then try again.

**How to fix it**

- End user: Close the open company file and open the connected one.
- You (developer): Retry after the end user opens the right file. If the company was renamed on purpose, reset the company file (POST /v1/end-users/{id}/reset-company-file) after confirming with the end user.

**Details**

- `details.openCompanyName`: Company name QuickBooks reported for the open file (when the snapshot proved the mismatch).
- `details.connectedCompanyName`: Company name of the file this connection was set up with.
- `details.channel`: `qbwc_connection_error` when inferred from the Web Connector (it reports 0x80040408 where the QuickBooks SDK reports 0x8004040A).
- `details.inferred`: `true` when the code was inferred from a Web Connector HRESULT rather than proven by the company snapshot.

End-user help: [A different company file is open](https://www.desktopaccountingapi.com/docs/help/connection-errors/wrong-company-file/).

### QBD_COMPANY_FILE_MISMATCH

- HTTP status: 409
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** The company file reports a different company identity than this connection.

**Cause.** The file looks like a copy or a different company than the one this connection was set up with.

**What the end user sees.** The open company file does not match the one that was connected. Please contact the application provider.

**How to fix it**

- You (developer): Confirm with the end user which file is correct, then reset the company file (POST /v1/end-users/{id}/reset-company-file) or reconnect with a new auth session.

Guide: [Connection status and health checks](https://www.desktopaccountingapi.com/docs/connect/connection-status/). End-user help: [A different company file is open](https://www.desktopaccountingapi.com/docs/help/connection-errors/wrong-company-file/).

### QBD_COMPANY_FILE_NOT_FOUND

- HTTP status: 503
- Retry: Change the request or the setup first
- Outcome: `not_applied`
- QuickBooks codes: `0x80040403`, `0x80040416`, `0x80040417`

**Message.** QuickBooks could not open the company file at its stored location.

**Cause.** The company file was moved, renamed or deleted, or QuickBooks was closed and no file path was available.

**What the end user sees.** QuickBooks Desktop could not find the company file. If it was moved or renamed, open it in QuickBooks, then try again.

**How to fix it**

- End user: Open the company file in QuickBooks Desktop and leave it open.
- You (developer): Reset the stored company file path (dashboard, or POST /v1/end-users/{id}/reset-company-file with mode `path`).

End-user help: [The company file cannot be found](https://www.desktopaccountingapi.com/docs/help/connection-errors/company-file-not-found/).

### QBD_FILE_MODE_CONFLICT

- HTTP status: 503
- Retry: Retry the same request
- Outcome: `not_applied`
- QuickBooks codes: `0x80040410`, `0x80040422`

**Message.** The company file is open in a mode that does not allow this connection.

**Cause.** The file is open in single-user mode by another application or user, or in a different file mode than requested.

**What the end user sees.** QuickBooks Desktop is using the company file in a way that blocks the connection. Switch to single-user mode or close other programs using the file, then try again.

**How to fix it**

- End user: Close other users or applications that have the file open, or switch the file mode in QuickBooks.

End-user help: [Single-user or multi-user mode conflict](https://www.desktopaccountingapi.com/docs/help/connection-errors/single-user-multi-user/).

### QBD_ADMIN_REQUIRED

- HTTP status: 503
- Retry: Change the request or the setup first
- Outcome: `not_applied`
- QuickBooks codes: `0x80040418`, `QBWC1039`

**Message.** The first connection to this company file must be authorized by the QuickBooks Admin user.

**Cause.** QuickBooks allows only the Admin user to grant an application first access to a company file.

**What the end user sees.** QuickBooks needs the Admin user to allow this connection the first time. Sign in to QuickBooks as Admin, in single-user mode, and run the Web Connector again.

**How to fix it**

- End user: Sign in to the company file as Admin in single-user mode and accept the authorization prompt.

End-user help: [Only the Admin can grant first access](https://www.desktopaccountingapi.com/docs/help/connection-errors/admin-required/).

### QBD_ACCESS_NOT_GRANTED

- HTTP status: 503
- Retry: Change the request or the setup first
- Outcome: `not_applied`
- QuickBooks codes: `0x80040420`, `0x8004041A`, `0x8004041D`

**Message.** QuickBooks has not granted this application access to the company file.

**Cause.** Access was denied at the authorization prompt, later revoked, or the application is not allowed to sign in automatically.

**What the end user sees.** QuickBooks Desktop has not allowed this connection. In QuickBooks, open Edit > Preferences > Integrated Applications and allow access for this application.

**How to fix it**

- End user: In QuickBooks, open Edit > Preferences > Integrated Applications > Company Preferences and allow this application, including access when QuickBooks is not running.

End-user help: [QuickBooks denied access to the app](https://www.desktopaccountingapi.com/docs/help/connection-errors/access-denied/).

### QBD_VERSION_UNSUPPORTED

- HTTP status: 503
- Retry: Change the request or the setup first
- Outcome: `not_applied`
- QuickBooks codes: `0x80040404`, `0x80040423`, `0x80040428`

**Message.** The installed QuickBooks Desktop version is not supported.

**Cause.** QuickBooks reports a qbXML version below 13.0 (QuickBooks 2014) or does not support the requested version.

**What the end user sees.** This version of QuickBooks Desktop is too old to connect. Update QuickBooks Desktop, then try again.

**How to fix it**

- End user: Update QuickBooks Desktop to a supported release.

End-user help: [This QuickBooks version is not supported](https://www.desktopaccountingapi.com/docs/help/connection-errors/quickbooks-version-unsupported/).

### REQUEST_TIMEOUT_NOT_SENT

- HTTP status: 504
- Retry: Retry the same request
- Outcome: `not_applied`

**Message.** The request timed out before it was sent to QuickBooks and was canceled.

**Cause.** The Web Connector did not pick up the request within Daapi-Timeout-Seconds. Nothing reached QuickBooks. `details.diagnosis` lists the probable causes the server observed (for example a QuickBooks dialog left open, or the Web Connector not running).

**What the end user sees.** QuickBooks Desktop did not respond in time. Please try again.

**How to fix it**

- You (developer): Retry with the same Idempotency-Key, or use a longer Daapi-Timeout-Seconds.
- End user: Make sure the computer running QuickBooks is on and the Web Connector is running.

**Details**

- `details.requestId`: The canceled request.
- `details.diagnosis`: Probable causes ranked by likelihood, with the connector last check-in (see the request diagnosis object).

Guide: [Request diagnosis](https://www.desktopaccountingapi.com/docs/troubleshooting/). End-user help: [Connection not active](https://www.desktopaccountingapi.com/docs/help/connection-errors/connection-not-active/).

### REQUEST_EXPIRED

- HTTP status: none (appears only on a request resource)
- Retry: Retry the same request
- Outcome: `not_applied`

**Message.** The request expired in the queue before it could be sent to QuickBooks.

**Cause.** The queue TTL passed while the connection was offline or busy. Nothing reached QuickBooks. `details.diagnosis` lists the probable causes.

**What the end user sees.** QuickBooks Desktop was not available in time. Please try again.

**How to fix it**

- You (developer): Submit the request again once the connection is online.

**Details**

- `details.diagnosis`: Probable causes ranked by likelihood (see the request diagnosis object).

Guide: [Request diagnosis](https://www.desktopaccountingapi.com/docs/troubleshooting/).

### QBD_REQUEST_TIMEOUT

- HTTP status: 504
- Retry: Read the request instead of resending
- Outcome: `pending`

**Message.** QuickBooks is still processing the request; the wait timed out.

**Cause.** The request reached QuickBooks but did not finish within Daapi-Timeout-Seconds. It keeps running.

**What the end user sees.** QuickBooks Desktop is taking longer than usual. The request is still being processed.

**How to fix it**

- You (developer): Poll GET /v1/requests/{details.requestId}?waitSeconds=60 for the result. Do not resend the request.

**Details**

- `details.requestId`: The request that keeps running.
- `details.diagnosis`: What the server observes about the running request.

Guide: [Request diagnosis](https://www.desktopaccountingapi.com/docs/troubleshooting/).

### QBD_READ_INTERRUPTED

- HTTP status: 502
- Retry: Retry the same request
- Outcome: `not_applicable`

**Message.** The connection to QuickBooks broke while reading; the automatic retry also failed.

**Cause.** The Web Connector session ended before QuickBooks returned the result of a read.

**What the end user sees.** The connection to QuickBooks Desktop was interrupted. Please try again.

**How to fix it**

- You (developer): Retry the read.

Guide: [Request lifecycle](https://www.desktopaccountingapi.com/docs/guides/request-lifecycle/).

## Integration error (`INTEGRATION_ERROR`)

QuickBooks rejected the request. Developer-actionable.

### QBD_REQUEST_ERROR

- HTTP status: 422
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** QuickBooks Desktop rejected the request.

**Cause.** QuickBooks returned an error status without a more specific mapping. `integrationCode` holds the qbXML statusCode and `details.qbxmlStatusMessage` its message.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Read details.qbxmlStatusMessage and correct the request.

**Details**

- `details.qbxmlStatusCode`: Native qbXML statusCode.
- `details.qbxmlStatusMessage`: Native qbXML statusMessage.

### QBD_OBJECT_NOT_FOUND

- HTTP status: 404
- Retry: Change the request or the setup first
- Outcome: `not_applied`
- QuickBooks codes: `500`, `3120`

**Message.** The QuickBooks object does not exist.

**Cause.** The ID does not exist in this company file, or the object was deleted in QuickBooks.

**What the end user sees.** The requested record was not found in QuickBooks Desktop.

**How to fix it**

- You (developer): Check the ID, or list the objects to find the current one.

### QBD_REFERENCE_NOT_FOUND

- HTTP status: 422
- Retry: Change the request or the setup first
- Outcome: `not_applied`
- QuickBooks codes: `3120`, `3140`

**Message.** A referenced QuickBooks object does not exist or has the wrong type.

**Cause.** A reference such as customerId or itemId points to an object that does not exist or is a different kind of object.

**What the end user sees.** The application sent a request QuickBooks could not accept. Please contact the application provider.

**How to fix it**

- You (developer): Fix the reference named in `param`.

### QBD_DUPLICATE_NAME

- HTTP status: 409
- Retry: Change the request or the setup first
- Outcome: `not_applied`
- QuickBooks codes: `3100`

**Message.** An object with this name already exists in QuickBooks.

**Cause.** QuickBooks names must be unique within a list, and across customers, vendors, employees and other names.

**What the end user sees.** A record with this name already exists in QuickBooks Desktop.

**How to fix it**

- You (developer): Use a different name, or look up and reuse the existing object.

### QBD_REVISION_NUMBER_STALE

- HTTP status: 409
- Retry: Change the request or the setup first
- Outcome: `not_applied`
- QuickBooks codes: `3200`

**Message.** The object changed since you read it; revisionNumber is out of date.

**Cause.** QuickBooks rejects updates that do not carry the current revision number, so concurrent edits are not lost.

**What the end user sees.** This record was changed by someone else. Reload it and try again.

**How to fix it**

- You (developer): Retrieve the object, merge your change, and update with the new revisionNumber.

Guide: [Updates and line items](https://www.desktopaccountingapi.com/docs/quickbooks/updates-and-line-items/).

### QBD_OBJECT_IN_USE

- HTTP status: 409
- Retry: Retry the same request
- Outcome: `not_applied`
- QuickBooks codes: `3175`, `3176`

**Message.** The QuickBooks object is in use: open or locked in QuickBooks, or still used by other records.

**Cause.** Usually the record is open for editing in QuickBooks or locked by another user in multi-user mode, which clears once it is closed. A deletion can also be refused because other records still use the object (for example an account referenced by a transaction); that does not clear with time.

**What the end user sees.** Someone is editing this record in QuickBooks Desktop. Close it in QuickBooks, then try again.

**How to fix it**

- End user: Close the record in QuickBooks Desktop.
- You (developer): Retry after a short wait. If a deletion still fails after the record is closed, other records use it: remove or change those first, or deactivate it instead of deleting.

End-user help: [A record is open or locked by another user](https://www.desktopaccountingapi.com/docs/help/connection-errors/record-in-use/).

### QBD_FEATURE_NOT_ENABLED

- HTTP status: 422
- Retry: Change the request or the setup first
- Outcome: `not_applied`
- QuickBooks codes: `3250`

**Message.** The QuickBooks feature this request needs is turned off or not available in this edition.

**Cause.** For example, inventory sites need Advanced Inventory, and some features must be turned on in Preferences.

**What the end user sees.** This feature is not turned on in QuickBooks Desktop.

**How to fix it**

- End user: Turn on the feature in QuickBooks Preferences, if the edition supports it.
- You (developer): Avoid the feature for this end user.

Guide: [Editions, versions and features](https://www.desktopaccountingapi.com/docs/quickbooks/editions-and-features/).

### QBD_INSUFFICIENT_PERMISSION

- HTTP status: 403
- Retry: Change the request or the setup first
- Outcome: `not_applied`
- QuickBooks codes: `3260`, `3261`

**Message.** The QuickBooks user or the integration lacks permission for this operation.

**Cause.** Status 3260: the connection signs in as the QuickBooks user chosen at authorization, and that user's role does not allow the operation. Status 3261: the integration has no permission to access personal data (for example payroll reports, Social Security numbers or credit card numbers), which the QuickBooks Admin grants in the Integrated Applications preferences.

**What the end user sees.** QuickBooks Desktop did not give this connection permission for this. Ask your QuickBooks Admin to update the permissions.

**How to fix it**

- End user: For status 3260: in QuickBooks, give the integration's user the required permission, or reauthorize with a user that has it.
- End user: For status 3261: signed in to QuickBooks as Admin, choose Edit > Preferences > Integrated Applications > Company Preferences, select the application, click Properties and allow it to access personal data.
- You (developer): Check integrationCode, then show the end user the matching fix; nothing was changed.

**Details**

- `details.qbxmlStatusCode`: Native qbXML statusCode: 3260 (user permission) or 3261 (personal data).
- `details.qbxmlStatusMessage`: Native qbXML statusMessage.

End-user help: [The QuickBooks user lacks permission](https://www.desktopaccountingapi.com/docs/help/connection-errors/insufficient-permission/).

### QBD_RESPONSE_TOO_LARGE

- HTTP status: 422
- Retry: Change the request or the setup first
- Outcome: `not_applicable`

**Message.** The QuickBooks response is larger than the API returns in one call.

**Cause.** The query matched more data than fits in one response.

**What the end user sees.** Something went wrong while contacting QuickBooks. Please try again in a moment.

**How to fix it**

- You (developer): Narrow the filters or use a paginated list.

Guide: [Pagination](https://www.desktopaccountingapi.com/docs/guides/pagination/).

## Outcome unknown error (`OUTCOME_UNKNOWN_ERROR`)

A write reached QuickBooks without a confirmed result. Never resend before checking.

### QBD_WRITE_OUTCOME_UNKNOWN

- HTTP status: 502
- Retry: Never resend; check QuickBooks first
- Outcome: `unknown`

**Message.** The write was sent to QuickBooks, but its result could not be confirmed.

**Cause.** The connection to the Web Connector broke after the request was handed to QuickBooks and before its response arrived.

**What the end user sees.** We could not confirm whether QuickBooks Desktop saved this change. Please check QuickBooks before trying again.

**How to fix it**

- You (developer): Do not resend. Check whether the object exists (by externalId or refNumber) before creating it again.
- Support: Open the request in the dashboard to see its timeline.

**Details**

- `details.requestId`: The uncertain request.
- `details.messageSetId`: qbXML newMessageSetID sent with the write.
- `details.reason`: How the session ended.

Guide: [Idempotency and safe retries](https://www.desktopaccountingapi.com/docs/guides/idempotency/).

## Internal error (`INTERNAL_ERROR`)

An unexpected error on our side. `outcome` says whether a write may have reached QuickBooks.

### QBD_RESPONSE_UNREADABLE

- HTTP status: 500
- Retry: Change the request or the setup first
- Outcome: `not_applicable`

**Message.** QuickBooks answered, but the response could not be converted to the documented JSON shape.

**Cause.** QuickBooks returned data that does not match the documented response schema (for example a value in an unexpected format). For a write, `outcome` is `applied`: QuickBooks saved the change. `details.issues` names the fields.

**What the end user sees.** Something went wrong while contacting QuickBooks. Please try again in a moment.

**How to fix it**

- You (developer): Do not resend a write whose outcome is applied. Retrieve the object by details.objectId (or list it) to read it, and contact support with the requestId.
- Support: Open the request in the dashboard; the stored qbXML response shows the unexpected value.

### INTERNAL_ERROR

- HTTP status: 500
- Retry: Change the request or the setup first
- Outcome: `not_applied`

**Message.** An unexpected error occurred on our side.

**Cause.** An unexpected server error. `outcome` says whether a write may have reached QuickBooks.

**What the end user sees.** Something went wrong while contacting QuickBooks. Please try again in a moment.

**How to fix it**

- You (developer): Retry reads. For writes, check `outcome` first and never resend when it is unknown.
- Support: Contact support with the requestId.

Guide: [Error handling](https://www.desktopaccountingapi.com/docs/guides/error-handling/).

### SERVICE_UNAVAILABLE

- HTTP status: 503
- Retry: Retry the same request
- Outcome: `not_applied`

**Message.** The service is temporarily unavailable. The request was not queued.

**Cause.** A dependency was unavailable before the request was accepted. Nothing reached QuickBooks.

**What the end user sees.** Something went wrong while contacting QuickBooks. Please try again in a moment.

**How to fix it**

- You (developer): Retry with backoff.

Guide: [Error handling](https://www.desktopaccountingapi.com/docs/guides/error-handling/).

## QuickBooks status codes

How qbXML status codes from QuickBooks map to error codes. Any other error status becomes `QBD_REQUEST_ERROR` with the status in `integrationCode`.

| qbXML status | Code | Note |
| --- | --- | --- |
| 1 | `QBD_OBJECT_NOT_FOUND` |  |
| 500 | `QBD_OBJECT_NOT_FOUND` |  |
| 3100 | `QBD_DUPLICATE_NAME` |  |
| 3120 | `QBD_REFERENCE_NOT_FOUND` | QBD_OBJECT_NOT_FOUND when the ID is the request target, QBD_REFERENCE_NOT_FOUND for a referenced ID. |
| 3140 | `QBD_REFERENCE_NOT_FOUND` |  |
| 3175 | `QBD_OBJECT_IN_USE` |  |
| 3176 | `QBD_OBJECT_IN_USE` |  |
| 3200 | `QBD_REVISION_NUMBER_STALE` |  |
| 3250 | `QBD_FEATURE_NOT_ENABLED` |  |
| 3260 | `QBD_INSUFFICIENT_PERMISSION` |  |
| 3261 | `QBD_INSUFFICIENT_PERMISSION` |  |