{ "$comment": "Generated from packages/api-contract/src/errors (catalog.ts, diagnosis.ts) and src/qbd/incompatibilities.ts by `npm run api:generate`. Do not edit.", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/", "errorTypes": [ { "type": "INVALID_REQUEST_ERROR", "description": "The request is invalid. Fix it before sending it again." }, { "type": "AUTHENTICATION_ERROR", "description": "The API key is missing or invalid." }, { "type": "PERMISSION_ERROR", "description": "The project may not perform this operation." }, { "type": "BILLING_ERROR", "description": "Billing pauses production data requests." }, { "type": "RATE_LIMIT_ERROR", "description": "Too many requests; retry after Retry-After." }, { "type": "INTEGRATION_CONNECTION_ERROR", "description": "The end user's environment (computer, Web Connector, QuickBooks) is not ready. Log as a warning; usually the end user must act." }, { "type": "INTEGRATION_ERROR", "description": "QuickBooks rejected the request. Developer-actionable." }, { "type": "OUTCOME_UNKNOWN_ERROR", "description": "A write reached QuickBooks without a confirmed result. Never resend before checking." }, { "type": "INTERNAL_ERROR", "description": "An unexpected error on our side. `outcome` says whether a write may have reached QuickBooks." } ], "retryGuidance": [ { "value": "retry_same_request", "description": "Repeating the identical request (same Idempotency-Key for writes) can succeed. SDKs retry it automatically with backoff." }, { "value": "poll_request", "description": "The request keeps running. Poll GET /v1/requests/{id}?waitSeconds=60; never resend it." }, { "value": "never_resend_check_first", "description": "Never resend automatically. Check in QuickBooks whether the change exists before trying again." }, { "value": "change_request_or_environment", "description": "Repeating the same request fails the same way. Change the request, or have the end user or developer apply a fix first." } ], "errors": [ { "code": "INVALID_JSON", "anchor": "invalid_json", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#invalid_json", "type": "INVALID_REQUEST_ERROR", "httpStatus": 400, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "The request body is not valid JSON.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "cause": "The body could not be parsed as JSON, or the Content-Type header does not match the body.", "fixes": [ { "actor": "developer", "action": "Send a UTF-8 JSON body with Content-Type: application/json." } ], "integrationCodes": [], "details": {} }, { "code": "INVALID_PARAMETER", "anchor": "invalid_parameter", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#invalid_parameter", "type": "INVALID_REQUEST_ERROR", "httpStatus": 400, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "A request parameter is invalid.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "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." } ], "integrationCodes": [], "details": {} }, { "code": "UNKNOWN_PARAMETER", "anchor": "unknown_parameter", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#unknown_parameter", "type": "INVALID_REQUEST_ERROR", "httpStatus": 400, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "The request contains a field this operation does not accept.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "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`." } ], "integrationCodes": [], "details": {} }, { "code": "UNKNOWN_HEADER", "anchor": "unknown_header", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#unknown_header", "type": "INVALID_REQUEST_ERROR", "httpStatus": 400, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "The request contains an unknown Daapi-* header.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "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." } ], "integrationCodes": [], "details": {} }, { "code": "DECIMAL_PRECISION_EXCEEDED", "anchor": "decimal_precision_exceeded", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#decimal_precision_exceeded", "type": "INVALID_REQUEST_ERROR", "httpStatus": 400, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "A decimal value has more decimal places than QuickBooks stores for this field.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "cause": "QuickBooks stores amounts with 2 decimal places and prices and quantities with 5. Values are never rounded silently.", "fixes": [ { "actor": "developer", "action": "Round the value named in `param` before sending it." } ], "integrationCodes": [], "details": {} }, { "code": "STRING_TOO_LONG", "anchor": "string_too_long", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#string_too_long", "type": "INVALID_REQUEST_ERROR", "httpStatus": 400, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "A text value is longer than QuickBooks allows for this field.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "cause": "Each QuickBooks text field has a maximum length.", "fixes": [ { "actor": "developer", "action": "Shorten the value named in `param` to the documented maximum length." } ], "integrationCodes": [], "details": {} }, { "code": "UNSUPPORTED_CHARACTER", "anchor": "unsupported_character", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#unsupported_character", "type": "INVALID_REQUEST_ERROR", "httpStatus": 400, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "A text value contains a character QuickBooks cannot store.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "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.", "fixes": [ { "actor": "developer", "action": "Replace the character reported in `details` in the field named in `param`; `details.suggestion` names a replacement when there is an obvious one." } ], "integrationCodes": [], "details": { "codePoint": "Unicode code point of the first rejected character.", "character": "The character itself, or null for control characters.", "index": "Its position in the value (0-based, in characters).", "suggestion": "A replacement QuickBooks can store, or null." } }, { "code": "FIELD_NOT_CLEARABLE", "anchor": "field_not_clearable", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#field_not_clearable", "type": "INVALID_REQUEST_ERROR", "httpStatus": 400, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "This field cannot be cleared with null.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "cause": "QuickBooks only supports clearing some fields. Fields that support it are marked x-daapi-clearable in the reference.", "fixes": [ { "actor": "developer", "action": "Omit the field to leave it unchanged, or send a replacement value." } ], "integrationCodes": [], "details": {} }, { "code": "END_USER_ID_MISSING", "anchor": "end_user_id_missing", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#end_user_id_missing", "type": "INVALID_REQUEST_ERROR", "httpStatus": 400, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "QuickBooks Desktop operations require the Daapi-End-User-Id header.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "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_...)." } ], "integrationCodes": [], "details": {} }, { "code": "PAYLOAD_TOO_LARGE", "anchor": "payload_too_large", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#payload_too_large", "type": "INVALID_REQUEST_ERROR", "httpStatus": 413, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "The request body is larger than 20 MiB.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "cause": "Request bodies are capped at 20 MiB.", "fixes": [ { "actor": "developer", "action": "Split the work into several smaller requests." } ], "integrationCodes": [], "details": {} }, { "code": "IDEMPOTENCY_KEY_INVALID", "anchor": "idempotency_key_invalid", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#idempotency_key_invalid", "type": "INVALID_REQUEST_ERROR", "httpStatus": 400, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "The Idempotency-Key header must be 1–255 printable ASCII characters.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "cause": "The Idempotency-Key value is empty, too long or contains characters outside printable ASCII.", "fixes": [ { "actor": "developer", "action": "Use a UUID or another value of 1–255 printable ASCII characters." } ], "integrationCodes": [], "details": {} }, { "code": "IDEMPOTENCY_KEY_REUSED", "anchor": "idempotency_key_reused", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#idempotency_key_reused", "type": "INVALID_REQUEST_ERROR", "httpStatus": 422, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "This Idempotency-Key was already used with a different request.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "cause": "A key identifies one logical request. The method, path, end user or body differs from the first use of this key.", "fixes": [ { "actor": "developer", "action": "Generate a new key for each logical request and reuse it only for retries of that request." } ], "integrationCodes": [], "details": {} }, { "code": "CURSOR_INVALID", "anchor": "cursor_invalid", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#cursor_invalid", "type": "INVALID_REQUEST_ERROR", "httpStatus": 400, "retryable": false, "outcome": "not_applicable", "retryGuidance": "change_request_or_environment", "message": "The cursor is malformed, out of date or belongs to another end user.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "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." } ], "integrationCodes": [], "details": {} }, { "code": "CURSOR_PARAMS_MISMATCH", "anchor": "cursor_params_mismatch", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#cursor_params_mismatch", "type": "INVALID_REQUEST_ERROR", "httpStatus": 400, "retryable": false, "outcome": "not_applicable", "retryGuidance": "change_request_or_environment", "message": "Filter parameters cannot change while paging with a cursor.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "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." } ], "integrationCodes": [], "details": {} }, { "code": "CURSOR_EXPIRED", "anchor": "cursor_expired", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#cursor_expired", "type": "INVALID_REQUEST_ERROR", "httpStatus": 410, "retryable": false, "outcome": "not_applicable", "retryGuidance": "change_request_or_environment", "message": "The cursor expired because QuickBooks discarded the underlying query.", "userFacingMessage": "Something went wrong while contacting QuickBooks. Please try again in a moment.", "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." } ], "integrationCodes": [], "details": { "reason": "`idle_timeout`, `session_ended`, `quickbooks_restarted` or `evicted`.", "pagesServed": "Pages returned before the cursor expired.", "recordsServed": "Records returned before the cursor expired." } }, { "code": "RESOURCE_MISSING", "anchor": "resource_missing", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#resource_missing", "type": "INVALID_REQUEST_ERROR", "httpStatus": 404, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "No such object exists in this project.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "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." } ], "integrationCodes": [], "details": {} }, { "code": "REQUEST_NOT_CANCELABLE", "anchor": "request_not_cancelable", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#request_not_cancelable", "type": "INVALID_REQUEST_ERROR", "httpStatus": 409, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "The request was already sent to QuickBooks and cannot be canceled.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "cause": "Cancellation is possible only before a request is handed to the Web Connector.", "fixes": [ { "actor": "developer", "action": "Wait for the request to finish with GET /v1/requests/{id}." } ], "integrationCodes": [], "details": {} }, { "code": "PASSTHROUGH_INVALID_QBXML", "anchor": "passthrough_invalid_qbxml", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#passthrough_invalid_qbxml", "type": "INVALID_REQUEST_ERROR", "httpStatus": 400, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "The passthrough body cannot be converted to a valid qbXML message set.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "cause": "Passthrough accepts qbXML request elements (names ending in Rq) as JSON or as a QBXMLMsgsRq XML fragment.", "fixes": [ { "actor": "developer", "action": "Send one or more request elements such as CustomerQueryRq; see `details` for the position of the problem." } ], "integrationCodes": [], "details": {} }, { "code": "QBD_FIELD_UNSUPPORTED_BY_VERSION", "anchor": "qbd_field_unsupported_by_version", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_field_unsupported_by_version", "type": "INVALID_REQUEST_ERROR", "httpStatus": 422, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "The connected QuickBooks version does not support this field or operation.", "userFacingMessage": "This feature needs a newer version of QuickBooks Desktop. Please contact the application provider.", "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." } ], "integrationCodes": [], "details": { "minimumQbxmlVersion": "qbXML version that introduced the field or operation.", "qbxmlVersion": "qbXML version of the connected QuickBooks." } }, { "code": "QBD_REGION_UNSUPPORTED", "anchor": "qbd_region_unsupported", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_region_unsupported", "type": "INVALID_REQUEST_ERROR", "httpStatus": 422, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "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.", "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." } ], "integrationCodes": [], "details": { "country": "Country code QuickBooks reported for the company file." } }, { "code": "API_KEY_MISSING", "anchor": "api_key_missing", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#api_key_missing", "type": "AUTHENTICATION_ERROR", "httpStatus": 401, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "No API key was provided. Send Authorization: Bearer .", "userFacingMessage": "This application could not connect to QuickBooks right now. Please contact the application provider.", "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." } ], "integrationCodes": [], "details": {} }, { "code": "API_KEY_INVALID", "anchor": "api_key_invalid", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#api_key_invalid", "type": "AUTHENTICATION_ERROR", "httpStatus": 401, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "The API key is invalid or has been revoked.", "userFacingMessage": "This application could not connect to QuickBooks right now. Please contact the application provider.", "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." } ], "integrationCodes": [], "details": {} }, { "code": "PUBLISHABLE_KEY_INVALID", "anchor": "publishable_key_invalid", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#publishable_key_invalid", "type": "AUTHENTICATION_ERROR", "httpStatus": 401, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "The publishable key is not valid.", "userFacingMessage": "This application could not connect to QuickBooks right now. Please contact the application provider.", "cause": "The publishableKey is malformed, unknown or was rotated.", "fixes": [ { "actor": "developer", "action": "Copy the current publishable key from the project's API keys page." } ], "integrationCodes": [], "details": {} }, { "code": "PUBLISHABLE_KEY_PROJECT_MISMATCH", "anchor": "publishable_key_project_mismatch", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#publishable_key_project_mismatch", "type": "PERMISSION_ERROR", "httpStatus": 403, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "The publishable key belongs to a different project than the secret key.", "userFacingMessage": "This application could not connect to QuickBooks right now. Please contact the application provider.", "cause": "Auth sessions must be created with a publishable key and a secret key from the same project.", "fixes": [ { "actor": "developer", "action": "Use the publishable key of the project that owns your secret key." } ], "integrationCodes": [], "details": {} }, { "code": "TEST_COMPANY_FILE_LIMIT_REACHED", "anchor": "test_company_file_limit_reached", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#test_company_file_limit_reached", "type": "PERMISSION_ERROR", "httpStatus": 403, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "Test projects in this organization already connect the maximum number of company files.", "userFacingMessage": "This application cannot connect another QuickBooks company file right now. Please contact the application provider.", "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.", "fixes": [ { "actor": "developer", "action": "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." }, { "actor": "support", "action": "Ask support to raise the limit for a legitimate test setup." } ], "integrationCodes": [], "details": { "used": "Company files connected across the organization test projects.", "limit": "The organization limit." } }, { "code": "API_KEY_READ_ONLY", "anchor": "api_key_read_only", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#api_key_read_only", "type": "PERMISSION_ERROR", "httpStatus": 403, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "This secret key is read-only and cannot change data.", "userFacingMessage": "This application could not connect to QuickBooks right now. Please contact the application provider.", "cause": "The request was made with a read-only secret key. Read-only keys can call GET operations and passthrough requests that contain only queries (`...QueryRq`). Creating, updating, deleting or voiding objects, writes through passthrough, auth sessions, end-user changes, request cancellation and webhook endpoint changes need a full-access key. The API rejects the request before anything is queued or sent to QuickBooks.", "fixes": [ { "actor": "developer", "action": "Use a full-access secret key for writes, or keep this key for read-only tools such as an MCP connection for AI agents." } ], "integrationCodes": [], "details": {} }, { "code": "PERMISSION_DENIED", "anchor": "permission_denied", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#permission_denied", "type": "PERMISSION_ERROR", "httpStatus": 403, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "This project is not allowed to perform this operation.", "userFacingMessage": "This application could not connect to QuickBooks right now. Please contact the application provider.", "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." } ], "integrationCodes": [], "details": {} }, { "code": "BILLING_REQUIRED", "anchor": "billing_required", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#billing_required", "type": "BILLING_ERROR", "httpStatus": 402, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "Production data requests are paused because the organization has no active subscription.", "userFacingMessage": "This application could not connect to QuickBooks right now. Please contact the application provider.", "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." } ], "integrationCodes": [], "details": {} }, { "code": "PAYMENT_FAILED", "anchor": "payment_failed", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#payment_failed", "type": "BILLING_ERROR", "httpStatus": 402, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "Production data requests are paused because payment failed.", "userFacingMessage": "This application could not connect to QuickBooks right now. Please contact the application provider.", "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." } ], "integrationCodes": [], "details": {} }, { "code": "RATE_LIMITED", "anchor": "rate_limited", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#rate_limited", "type": "RATE_LIMIT_ERROR", "httpStatus": 429, "retryable": true, "outcome": "not_applied", "retryGuidance": "retry_same_request", "message": "Too many requests for this project. Retry after the time in Retry-After.", "userFacingMessage": "Something went wrong while contacting QuickBooks. Please try again in a moment.", "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." } ], "integrationCodes": [], "details": { "scope": "`project` (requests per project across all keys) or `ip` (requests or failed authentications from one IP address).", "limit": "Requests allowed per window.", "windowSeconds": "Window length in seconds." } }, { "code": "CONNECTION_QUEUE_FULL", "anchor": "connection_queue_full", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#connection_queue_full", "type": "RATE_LIMIT_ERROR", "httpStatus": 429, "retryable": true, "outcome": "not_applied", "retryGuidance": "retry_same_request", "message": "This connection has too many pending requests.", "userFacingMessage": "Something went wrong while contacting QuickBooks. Please try again in a moment.", "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." } ], "integrationCodes": [], "details": { "reason": "`pending_requests` or `sync_waiters`.", "limit": "The limit that applied." } }, { "code": "WEBHOOK_ENDPOINT_LIMIT_REACHED", "anchor": "webhook_endpoint_limit_reached", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#webhook_endpoint_limit_reached", "type": "INVALID_REQUEST_ERROR", "httpStatus": 422, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "This project already has the maximum number of webhook endpoints.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "cause": "A project can register up to 20 webhook endpoints.", "fixes": [ { "actor": "developer", "action": "Delete an endpoint you no longer use, or subscribe one endpoint to more event types." } ], "integrationCodes": [], "details": { "limit": "Maximum endpoints per project." } }, { "code": "INTEGRATION_CONNECTION_NOT_SET_UP", "anchor": "integration_connection_not_set_up", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#integration_connection_not_set_up", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 409, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "This end user has not finished connecting QuickBooks Desktop.", "userFacingMessage": "QuickBooks Desktop is not connected yet. Finish the connection setup to continue.", "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." } ], "integrationCodes": [], "details": {} }, { "code": "INTEGRATION_CONNECTION_NOT_ACTIVE", "anchor": "integration_connection_not_active", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#integration_connection_not_active", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 503, "retryable": true, "outcome": "not_applied", "retryGuidance": "retry_same_request", "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.", "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." } ], "integrationCodes": [], "details": {} }, { "code": "INTEGRATION_CONNECTION_DISABLED", "anchor": "integration_connection_disabled", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#integration_connection_disabled", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 403, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "This connection is disabled.", "userFacingMessage": "This QuickBooks connection is turned off. Please contact the application provider.", "cause": "The connection was disabled in the dashboard.", "fixes": [ { "actor": "developer", "action": "Enable the connection in the dashboard, or create a new auth session." } ], "integrationCodes": [], "details": {} }, { "code": "QBD_CONNECTION_ERROR", "anchor": "qbd_connection_error", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_connection_error", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 503, "retryable": true, "outcome": "not_applied", "retryGuidance": "retry_same_request", "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.", "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." } ], "integrationCodes": [], "details": {} }, { "code": "QBD_CANNOT_START", "anchor": "qbd_cannot_start", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_cannot_start", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 503, "retryable": true, "outcome": "not_applied", "retryGuidance": "retry_same_request", "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.", "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." } ], "integrationCodes": [ "0x80040408", "0x80040401" ], "details": {} }, { "code": "QBD_STARTING", "anchor": "qbd_starting", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_starting", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 503, "retryable": true, "outcome": "not_applied", "retryGuidance": "retry_same_request", "message": "QuickBooks Desktop is still starting.", "userFacingMessage": "QuickBooks Desktop is still opening. Please try again in a minute.", "cause": "QuickBooks had not finished opening the company file when the Web Connector connected.", "fixes": [ { "actor": "developer", "action": "Retry after a short wait." } ], "integrationCodes": [ "0x80040424", "0x8004042D" ], "details": {} }, { "code": "QBD_MODAL_DIALOG_OPEN", "anchor": "qbd_modal_dialog_open", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_modal_dialog_open", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 503, "retryable": true, "outcome": "not_applied", "retryGuidance": "retry_same_request", "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.", "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." } ], "integrationCodes": [ "0x80040414", "QBWC1053" ], "details": {} }, { "code": "QBD_QUICKBOOKS_NOT_RESPONDING", "anchor": "qbd_quickbooks_not_responding", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_quickbooks_not_responding", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 503, "retryable": true, "outcome": "not_applied", "retryGuidance": "retry_same_request", "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.", "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." } ], "integrationCodes": [ "QBWC1053", "QBWC1079" ], "details": { "requestId": "The request that was not sent.", "diagnosis": "Probable causes ranked by likelihood." } }, { "code": "QBD_WRONG_COMPANY_FILE_OPEN", "anchor": "qbd_wrong_company_file_open", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_wrong_company_file_open", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 503, "retryable": true, "outcome": "not_applied", "retryGuidance": "retry_same_request", "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.", "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." } ], "integrationCodes": [ "0x8004040A" ], "details": { "openCompanyName": "Company name QuickBooks reported for the open file (when the snapshot proved the mismatch).", "connectedCompanyName": "Company name of the file this connection was set up with.", "channel": "`qbwc_connection_error` when inferred from the Web Connector (it reports 0x80040408 where the QuickBooks SDK reports 0x8004040A).", "inferred": "`true` when the code was inferred from a Web Connector HRESULT rather than proven by the company snapshot." } }, { "code": "QBD_COMPANY_FILE_MISMATCH", "anchor": "qbd_company_file_mismatch", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_company_file_mismatch", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 409, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "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.", "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." } ], "integrationCodes": [], "details": {} }, { "code": "QBD_COMPANY_FILE_NOT_FOUND", "anchor": "qbd_company_file_not_found", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_company_file_not_found", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 503, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "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.", "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`)." } ], "integrationCodes": [ "0x80040403", "0x80040416", "0x80040417" ], "details": {} }, { "code": "QBD_FILE_MODE_CONFLICT", "anchor": "qbd_file_mode_conflict", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_file_mode_conflict", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 503, "retryable": true, "outcome": "not_applied", "retryGuidance": "retry_same_request", "message": "The company file is open in a mode that does not allow this connection.", "userFacingMessage": "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.", "cause": "The file is open in single-user mode by another application or user, or in a different file mode than requested.", "fixes": [ { "actor": "end_user", "action": "Close other users or applications that have the file open, or switch the file mode in QuickBooks." } ], "integrationCodes": [ "0x80040410", "0x80040422" ], "details": {} }, { "code": "QBD_ADMIN_REQUIRED", "anchor": "qbd_admin_required", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_admin_required", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 503, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "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.", "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." } ], "integrationCodes": [ "0x80040418", "QBWC1039" ], "details": {} }, { "code": "QBD_ACCESS_NOT_GRANTED", "anchor": "qbd_access_not_granted", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_access_not_granted", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 503, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "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.", "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." } ], "integrationCodes": [ "0x80040420", "0x8004041A", "0x8004041D" ], "details": {} }, { "code": "QBD_VERSION_UNSUPPORTED", "anchor": "qbd_version_unsupported", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_version_unsupported", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 503, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "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.", "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." } ], "integrationCodes": [ "0x80040404", "0x80040423", "0x80040428" ], "details": {} }, { "code": "QBD_REQUEST_ERROR", "anchor": "qbd_request_error", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_request_error", "type": "INTEGRATION_ERROR", "httpStatus": 422, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "QuickBooks Desktop rejected the request.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "cause": "QuickBooks returned an error status without a more specific mapping. `integrationCode` holds the qbXML statusCode and `details.qbxmlStatusMessage` its message.", "fixes": [ { "actor": "developer", "action": "Read details.qbxmlStatusMessage and correct the request." } ], "integrationCodes": [], "details": { "qbxmlStatusCode": "Native qbXML statusCode.", "qbxmlStatusMessage": "Native qbXML statusMessage." } }, { "code": "QBD_OBJECT_NOT_FOUND", "anchor": "qbd_object_not_found", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_object_not_found", "type": "INTEGRATION_ERROR", "httpStatus": 404, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "The QuickBooks object does not exist.", "userFacingMessage": "The requested record was not found in QuickBooks Desktop.", "cause": "The ID does not exist in this company file, or the object was deleted in QuickBooks.", "fixes": [ { "actor": "developer", "action": "Check the ID, or list the objects to find the current one." } ], "integrationCodes": [ "500", "3120" ], "details": {} }, { "code": "QBD_REFERENCE_NOT_FOUND", "anchor": "qbd_reference_not_found", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_reference_not_found", "type": "INTEGRATION_ERROR", "httpStatus": 422, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "A referenced QuickBooks object does not exist or has the wrong type.", "userFacingMessage": "The application sent a request QuickBooks could not accept. Please contact the application provider.", "cause": "A reference such as customerId or itemId points to an object that does not exist or is a different kind of object.", "fixes": [ { "actor": "developer", "action": "Fix the reference named in `param`." } ], "integrationCodes": [ "3120", "3140" ], "details": {} }, { "code": "QBD_DUPLICATE_NAME", "anchor": "qbd_duplicate_name", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_duplicate_name", "type": "INTEGRATION_ERROR", "httpStatus": 409, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "An object with this name already exists in QuickBooks.", "userFacingMessage": "A record with this name already exists in QuickBooks Desktop.", "cause": "QuickBooks names must be unique within a list, and across customers, vendors, employees and other names.", "fixes": [ { "actor": "developer", "action": "Use a different name, or look up and reuse the existing object." } ], "integrationCodes": [ "3100" ], "details": {} }, { "code": "QBD_REVISION_NUMBER_STALE", "anchor": "qbd_revision_number_stale", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_revision_number_stale", "type": "INTEGRATION_ERROR", "httpStatus": 409, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "The object changed since you read it; revisionNumber is out of date.", "userFacingMessage": "This record was changed by someone else. Reload it and try again.", "cause": "QuickBooks rejects updates that do not carry the current revision number, so concurrent edits are not lost.", "fixes": [ { "actor": "developer", "action": "Retrieve the object, merge your change, and update with the new revisionNumber." } ], "integrationCodes": [ "3200" ], "details": {} }, { "code": "QBD_OBJECT_IN_USE", "anchor": "qbd_object_in_use", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_object_in_use", "type": "INTEGRATION_ERROR", "httpStatus": 409, "retryable": true, "outcome": "not_applied", "retryGuidance": "retry_same_request", "message": "The QuickBooks object is in use: open or locked in QuickBooks, or still used by other records.", "userFacingMessage": "Someone is editing this record in QuickBooks Desktop. Close it in QuickBooks, then try again.", "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.", "fixes": [ { "actor": "end_user", "action": "Close the record in QuickBooks Desktop." }, { "actor": "developer", "action": "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." } ], "integrationCodes": [ "3175", "3176" ], "details": {} }, { "code": "QBD_FEATURE_NOT_ENABLED", "anchor": "qbd_feature_not_enabled", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_feature_not_enabled", "type": "INTEGRATION_ERROR", "httpStatus": 422, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "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.", "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." } ], "integrationCodes": [ "3250" ], "details": {} }, { "code": "QBD_INSUFFICIENT_PERMISSION", "anchor": "qbd_insufficient_permission", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_insufficient_permission", "type": "INTEGRATION_ERROR", "httpStatus": 403, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "The QuickBooks user or the integration lacks permission for this operation.", "userFacingMessage": "QuickBooks Desktop did not give this connection permission for this. Ask your QuickBooks Admin to update the permissions.", "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, choose Edit > Preferences > Integrated Applications > Company Preferences, select the application, click Properties and allow it to access personal data." }, { "actor": "developer", "action": "Check integrationCode, then show the end user the matching fix; nothing was changed." } ], "integrationCodes": [ "3260", "3261" ], "details": { "qbxmlStatusCode": "Native qbXML statusCode: 3260 (user permission) or 3261 (personal data).", "qbxmlStatusMessage": "Native qbXML statusMessage." } }, { "code": "QBD_RESPONSE_TOO_LARGE", "anchor": "qbd_response_too_large", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_response_too_large", "type": "INTEGRATION_ERROR", "httpStatus": 422, "retryable": false, "outcome": "not_applicable", "retryGuidance": "change_request_or_environment", "message": "The QuickBooks response is larger than the API returns in one call.", "userFacingMessage": "Something went wrong while contacting QuickBooks. Please try again in a moment.", "cause": "The query matched more data than fits in one response.", "fixes": [ { "actor": "developer", "action": "Narrow the filters or use a paginated list." } ], "integrationCodes": [], "details": {} }, { "code": "QBD_OPERATION_UNSUPPORTED", "anchor": "qbd_operation_unsupported", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_operation_unsupported", "type": "INVALID_REQUEST_ERROR", "httpStatus": 422, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "QuickBooks Desktop offers no way to perform this operation through its integration interface.", "userFacingMessage": "This action is not available for QuickBooks Desktop. Please contact the application provider.", "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.", "fixes": [ { "actor": "developer", "action": "Use one of the alternatives in details.alternatives, for example deleting the transaction instead of voiding it." }, { "actor": "end_user", "action": "Perform the action in the QuickBooks Desktop window." } ], "integrationCodes": [], "details": { "operationId": "The unsupported operation.", "alternatives": "What to do instead." } }, { "code": "QBD_RESPONSE_UNREADABLE", "anchor": "qbd_response_unreadable", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_response_unreadable", "type": "INTERNAL_ERROR", "httpStatus": 500, "retryable": false, "outcome": "not_applicable", "retryGuidance": "change_request_or_environment", "message": "QuickBooks answered, but the response could not be converted to the documented JSON shape.", "userFacingMessage": "Something went wrong while contacting QuickBooks. Please try again in a moment.", "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.", "fixes": [ { "actor": "developer", "action": "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." }, { "actor": "support", "action": "Open the request in the dashboard; the stored qbXML response shows the unexpected value." } ], "integrationCodes": [], "details": {} }, { "code": "REQUEST_TIMEOUT_NOT_SENT", "anchor": "request_timeout_not_sent", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#request_timeout_not_sent", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 504, "retryable": true, "outcome": "not_applied", "retryGuidance": "retry_same_request", "message": "The request timed out before it was sent to QuickBooks and was canceled.", "userFacingMessage": "QuickBooks Desktop did not respond in time. Please try again.", "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." } ], "integrationCodes": [], "details": { "requestId": "The canceled request.", "diagnosis": "Probable causes ranked by likelihood, with the connector last check-in (see the request diagnosis object)." } }, { "code": "REQUEST_EXPIRED", "anchor": "request_expired", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#request_expired", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": null, "retryable": true, "outcome": "not_applied", "retryGuidance": "retry_same_request", "message": "The request expired in the queue before it could be sent to QuickBooks.", "userFacingMessage": "QuickBooks Desktop was not available in time. Please try again.", "cause": "The queue TTL passed while the connection was offline or busy. Nothing reached QuickBooks. `details.diagnosis` lists the probable causes.", "fixes": [ { "actor": "developer", "action": "Submit the request again once the connection is online." } ], "integrationCodes": [], "details": { "diagnosis": "Probable causes ranked by likelihood (see the request diagnosis object)." } }, { "code": "REQUEST_CANCELED", "anchor": "request_canceled", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#request_canceled", "type": "INVALID_REQUEST_ERROR", "httpStatus": null, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "The request was canceled before it was sent to QuickBooks.", "userFacingMessage": "The request was canceled.", "cause": "The request was canceled by the caller before the Web Connector picked it up.", "fixes": [ { "actor": "developer", "action": "Submit a new request if the work is still needed." } ], "integrationCodes": [], "details": {} }, { "code": "QBD_REQUEST_TIMEOUT", "anchor": "qbd_request_timeout", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_request_timeout", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 504, "retryable": false, "outcome": "pending", "retryGuidance": "poll_request", "message": "QuickBooks is still processing the request; the wait timed out.", "userFacingMessage": "QuickBooks Desktop is taking longer than usual. The request is still being processed.", "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." } ], "integrationCodes": [], "details": { "requestId": "The request that keeps running.", "diagnosis": "What the server observes about the running request." } }, { "code": "QBD_WRITE_OUTCOME_UNKNOWN", "anchor": "qbd_write_outcome_unknown", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_write_outcome_unknown", "type": "OUTCOME_UNKNOWN_ERROR", "httpStatus": 502, "retryable": false, "outcome": "unknown", "retryGuidance": "never_resend_check_first", "message": "The write was sent to QuickBooks, but its result could not be confirmed.", "userFacingMessage": "We could not confirm whether QuickBooks Desktop saved this change. Please check QuickBooks before trying again.", "cause": "The connection to the Web Connector broke after the request was handed to QuickBooks and before its response arrived.", "fixes": [ { "actor": "developer", "action": "Do not resend. Check whether the object exists (by externalId or refNumber) before creating it again." }, { "actor": "support", "action": "Open the request in the dashboard to see its timeline." } ], "integrationCodes": [], "details": { "requestId": "The uncertain request.", "messageSetId": "qbXML newMessageSetID sent with the write.", "reason": "How the session ended." } }, { "code": "QBD_READ_INTERRUPTED", "anchor": "qbd_read_interrupted", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#qbd_read_interrupted", "type": "INTEGRATION_CONNECTION_ERROR", "httpStatus": 502, "retryable": true, "outcome": "not_applicable", "retryGuidance": "retry_same_request", "message": "The connection to QuickBooks broke while reading; the automatic retry also failed.", "userFacingMessage": "The connection to QuickBooks Desktop was interrupted. Please try again.", "cause": "The Web Connector session ended before QuickBooks returned the result of a read.", "fixes": [ { "actor": "developer", "action": "Retry the read." } ], "integrationCodes": [], "details": {} }, { "code": "INTERNAL_ERROR", "anchor": "internal_error", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#internal_error", "type": "INTERNAL_ERROR", "httpStatus": 500, "retryable": false, "outcome": "not_applied", "retryGuidance": "change_request_or_environment", "message": "An unexpected error occurred on our side.", "userFacingMessage": "Something went wrong while contacting QuickBooks. Please try again in a moment.", "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." } ], "integrationCodes": [], "details": {} }, { "code": "SERVICE_UNAVAILABLE", "anchor": "service_unavailable", "docsUrl": "https://www.desktopaccountingapi.com/docs/errors/#service_unavailable", "type": "INTERNAL_ERROR", "httpStatus": 503, "retryable": true, "outcome": "not_applied", "retryGuidance": "retry_same_request", "message": "The service is temporarily unavailable. The request was not queued.", "userFacingMessage": "Something went wrong while contacting QuickBooks. Please try again in a moment.", "cause": "A dependency was unavailable before the request was accepted. Nothing reached QuickBooks.", "fixes": [ { "actor": "developer", "action": "Retry with backoff." } ], "integrationCodes": [], "details": {} } ], "nativeStatusMapping": [ { "statusCode": 1, "code": "QBD_OBJECT_NOT_FOUND", "note": null }, { "statusCode": 500, "code": "QBD_OBJECT_NOT_FOUND", "note": null }, { "statusCode": 3100, "code": "QBD_DUPLICATE_NAME", "note": null }, { "statusCode": 3120, "code": "QBD_REFERENCE_NOT_FOUND", "note": "QBD_OBJECT_NOT_FOUND when the ID is the request target, QBD_REFERENCE_NOT_FOUND for a referenced ID." }, { "statusCode": 3140, "code": "QBD_REFERENCE_NOT_FOUND", "note": null }, { "statusCode": 3175, "code": "QBD_OBJECT_IN_USE", "note": null }, { "statusCode": 3176, "code": "QBD_OBJECT_IN_USE", "note": null }, { "statusCode": 3200, "code": "QBD_REVISION_NUMBER_STALE", "note": null }, { "statusCode": 3250, "code": "QBD_FEATURE_NOT_ENABLED", "note": null }, { "statusCode": 3260, "code": "QBD_INSUFFICIENT_PERMISSION", "note": null }, { "statusCode": 3261, "code": "QBD_INSUFFICIENT_PERMISSION", "note": null } ], "diagnosis": { "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/", "causes": [ { "code": "quickbooks_modal_dialog", "anchor": "quickbooks_modal_dialog", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#quickbooks_modal_dialog", "summary": "QuickBooks Desktop probably has a dialog window open.", "explanation": "The Web Connector checked in and started a session, but QuickBooks never answered it. The Web Connector reports an open dialog (QBWC1053) only in its own window and keeps retrying about once a minute, so the server sees check-ins followed by silence.", "signals": "A session opened by authenticate gets no sendRequestXML (no company snapshot) within the silent-session window, and the Web Connector re-authenticates roughly every 60 seconds.", "fixes": [ { "actor": "end_user", "action": "On the computer that runs QuickBooks, close any open QuickBooks dialog (backup reminder, update prompt, login or \"Do you want to save\" window)." }, { "actor": "developer", "action": "Keep the request queued (async) or retry with the same Idempotency-Key after the end user confirms." } ] }, { "code": "web_connector_registration_lost", "anchor": "web_connector_registration_lost", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#web_connector_registration_lost", "summary": "The company file may have lost its Web Connector registration (restored from an older backup).", "explanation": "The Web Connector keeps a lock record inside the company file. Restoring a backup made before this application was added removes it; the Web Connector then fails locally (QBWC1079, status 3120 for AppLock) after checking in, which looks like silence to the server.", "signals": "Same as a modal dialog: sessions start and QuickBooks never answers. Ask the end user whether the company file was restored recently.", "fixes": [ { "actor": "end_user", "action": "In the Web Connector, remove this application and add it again with the same QWC file (or create a new setup link), then enter the password again." }, { "actor": "developer", "action": "Create a new auth session if the end user no longer has the QWC file." } ] }, { "code": "quickbooks_starting", "anchor": "quickbooks_starting", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#quickbooks_starting", "summary": "QuickBooks Desktop is starting or opening the company file.", "explanation": "The Web Connector started a session and QuickBooks has not answered yet. Opening a large company file or starting QuickBooks without a user can take a minute or more.", "signals": "A session opened recently and QuickBooks has not answered yet; no earlier silent sessions.", "fixes": [ { "actor": "developer", "action": "Wait and poll the request; it is sent as soon as QuickBooks answers." }, { "actor": "end_user", "action": "Keep QuickBooks open with the company file loaded to avoid start-up delays." } ] }, { "code": "other_web_connector_app", "anchor": "other_web_connector_app", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#other_web_connector_app", "summary": "Another Web Connector application may be running an update.", "explanation": "The Web Connector runs one application at a time. Another vendor's long update (\"Another update is in progress\") delays our session.", "signals": "Check-ins are late or a session waits for QuickBooks while other applications are registered in the Web Connector.", "fixes": [ { "actor": "end_user", "action": "Open the Web Connector and check whether another application is updating; let it finish." } ] }, { "code": "web_connector_closed", "anchor": "web_connector_closed", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#web_connector_closed", "summary": "The QuickBooks Web Connector is not running.", "explanation": "The Web Connector stopped checking in after a regular polling pattern. It is closed, was not started after a sign-in, or Auto-Run is unchecked for this application.", "signals": "No authenticate call within the offline threshold after regular check-ins.", "fixes": [ { "actor": "end_user", "action": "Start the QuickBooks Web Connector on the computer that runs QuickBooks and make sure Auto-Run is checked for this application." }, { "actor": "developer", "action": "Use async requests (Prefer: respond-async) so work waits for the connection instead of failing." } ] }, { "code": "computer_offline", "anchor": "computer_offline", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#computer_offline", "summary": "The computer that runs QuickBooks is probably off, asleep or offline.", "explanation": "Nothing from the Web Connector has arrived for a long time. A computer that sleeps, restarts or loses its network stops all check-ins.", "signals": "No authenticate call for a long period (more than about 30 minutes).", "fixes": [ { "actor": "end_user", "action": "Turn on or wake the computer that runs QuickBooks, sign in to Windows and check its internet connection. Disable sleep if it must be reachable at all times." } ] }, { "code": "web_connector_schedule_changed", "anchor": "web_connector_schedule_changed", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#web_connector_schedule_changed", "summary": "The Web Connector is set to check in only every few minutes.", "explanation": "The interval between check-ins rose above 60 seconds, which happens when someone sets the \"Every Min\" column for this application.", "signals": "Three consecutive check-in intervals above 60 seconds.", "fixes": [ { "actor": "end_user", "action": "In the Web Connector, clear the \"Every Min\" value for this application (or remove and add it again) so it checks in in real time." } ] }, { "code": "quickbooks_closed_no_unattended_access", "anchor": "quickbooks_closed_no_unattended_access", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#quickbooks_closed_no_unattended_access", "summary": "QuickBooks is closed and this application may not open it.", "explanation": "QuickBooks reported that it could not be started for the Web Connector, or that access was not granted. When the application was authorized without \"allow access even if QuickBooks is not running\", QuickBooks must stay open.", "signals": "The Web Connector reported connectionError with 0x8004041D, 0x80040420, 0x80040408 or a similar HRESULT.", "fixes": [ { "actor": "end_user", "action": "Open QuickBooks with the company file, or in QuickBooks go to Edit > Preferences > Integrated Applications and allow this application to log in automatically." } ] }, { "code": "quickbooks_unavailable", "anchor": "quickbooks_unavailable", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#quickbooks_unavailable", "summary": "QuickBooks reported an error when the Web Connector tried to open it.", "explanation": "The Web Connector reached QuickBooks, which refused the connection. The connection error code says why.", "signals": "connectionError HRESULTs from the Web Connector in recent sessions.", "fixes": [ { "actor": "developer", "action": "Look up the error code in `details` (or the connection statusReason) in the error reference and follow its fixes." } ] }, { "code": "wrong_company_file", "anchor": "wrong_company_file", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#wrong_company_file", "summary": "A different company file is open in QuickBooks.", "explanation": "QuickBooks answered with a company file whose identity differs from the one this connection was set up with, so nothing was sent.", "signals": "The Host/Company snapshot of the session reports a different company identity.", "fixes": [ { "actor": "end_user", "action": "Open the company file this connection was set up with." }, { "actor": "developer", "action": "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." } ] }, { "code": "write_recovery_pending", "anchor": "write_recovery_pending", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#write_recovery_pending", "summary": "A write is waiting for an earlier write with an unknown outcome.", "explanation": "An earlier write reached QuickBooks without a confirmed result. Later writes wait so they cannot overwrite QuickBooks' recovery state. Reads continue.", "signals": "The connection holds a write barrier.", "fixes": [ { "actor": "developer", "action": "Check the earlier request (details.barrierRequestId); the barrier lifts when its session ends or recovery resolves it." } ] }, { "code": "behind_other_requests", "anchor": "behind_other_requests", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#behind_other_requests", "summary": "The request is waiting behind other requests.", "explanation": "QuickBooks processes one request at a time per company file. Earlier requests on this connection run first.", "signals": "Requests ahead in the connection queue.", "fixes": [ { "actor": "developer", "action": "Spread bulk work over time, use async requests, or narrow large reads." } ] }, { "code": "quickbooks_processing", "anchor": "quickbooks_processing", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#quickbooks_processing", "summary": "QuickBooks is still processing the request.", "explanation": "The request was handed to QuickBooks and the session is still active. Large reports and long lists can take minutes.", "signals": "The request is sent and its session made a SOAP call recently.", "fixes": [ { "actor": "developer", "action": "Poll GET /v1/requests/{id}?waitSeconds=60. Do not resend." } ] }, { "code": "session_interrupted", "anchor": "session_interrupted", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#session_interrupted", "summary": "The Web Connector stopped responding while QuickBooks had the request.", "explanation": "The request was sent, then the session went silent. The computer may have gone to sleep or the Web Connector was closed mid-request.", "signals": "The request is sent and its session made no SOAP call for longer than the offline threshold.", "fixes": [ { "actor": "end_user", "action": "Check that the computer running QuickBooks is awake and the Web Connector is open." }, { "actor": "developer", "action": "Wait for the request to finish or to become outcome_unknown; never resend a write before checking it." } ] }, { "code": "same_connector_two_computers", "anchor": "same_connector_two_computers", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#same_connector_two_computers", "summary": "The same connector file is installed on two computers.", "explanation": "Two computers check in with the same Web Connector username, for example two workstations of a multi-user company file. Only one may work at a time: the other is told to wait while a session is open, so requests take longer and updates alternate between the computers.", "signals": "A check-in from a second computer (different network address) for the same connector while the first computer had a live session.", "fixes": [ { "actor": "end_user", "action": "Keep the connector in the Web Connector of one computer only, the one that stays on with QuickBooks open. Remove it from the other computer's Web Connector." }, { "actor": "developer", "action": "If both computers must stay connected, create a separate end user (and setup link) for each." } ] }, { "code": "awaiting_check_in", "anchor": "awaiting_check_in", "docsUrl": "https://www.desktopaccountingapi.com/docs/troubleshooting/#awaiting_check_in", "summary": "The request is waiting for the next Web Connector check-in.", "explanation": "The Web Connector checks in every few seconds; the request is sent at the next check-in.", "signals": "The connector checks in regularly and nothing else blocks the request.", "fixes": [ { "actor": "developer", "action": "No action needed; allow for the check-in interval in your timeout." } ] } ] }, "incompatibilities": [ { "id": "qbd.salesTaxPaymentChecks.void", "kind": "operation_unsupported", "title": "POST /v1/quickbooks-desktop/sales-tax-payment-checks/{id}/void is not available", "operationIds": [ "qbd.salesTaxPaymentChecks.void" ], "description": "QuickBooks Desktop's SDK has no void request for SalesTaxPaymentCheck (it is not a qbXML TxnVoidType), so the operation is not offered.", "behavior": "The API answers 422 QBD_OPERATION_UNSUPPORTED with details.alternatives; nothing is sent to QuickBooks.", "errorCode": "QBD_OPERATION_UNSUPPORTED", "alternatives": [ "DELETE /v1/quickbooks-desktop/sales-tax-payment-checks/{id} deletes the transaction instead.", "Void it in the QuickBooks Desktop window." ], "evidence": "qbxml_schema" }, { "id": "qbd.payrollWageItems.list.no_iterator", "kind": "no_native_pagination", "title": "Payroll wage items list without cursor pagination", "operationIds": [ "qbd.payrollWageItems.list" ], "description": "qbXML declares no iterator for the payroll wage item query, so the list cannot be paged with a cursor. Conductor documents cursor pagination for this list.", "behavior": "The list returns every matching record in one page with nextCursor null, hasMore false and remainingCount 0, so a Conductor pagination loop stops after it. A cursor parameter returns 400 CURSOR_INVALID: there is never one to send.", "errorCode": null, "alternatives": [ "Use limit and the name filters to narrow the result." ], "evidence": "qbxml_schema" }, { "id": "small_lists.no_iterator", "kind": "no_native_pagination", "title": "Small lists return every record", "operationIds": [ "qbd.accountTaxLines.list", "qbd.accounts.list", "qbd.billsToPay.list", "qbd.classes.list", "qbd.currencies.list", "qbd.customerTypes.list", "qbd.dateDrivenTerms.list", "qbd.deletedListObjects.list", "qbd.deletedTransactions.list", "qbd.employees.list", "qbd.inventoryAdjustments.list", "qbd.inventorySites.list", "qbd.otherNames.list", "qbd.paymentMethods.list", "qbd.paymentsToDeposit.list", "qbd.priceLevels.list", "qbd.salesRepresentatives.list", "qbd.salesTaxCodes.list", "qbd.shippingMethods.list", "qbd.standardTerms.list", "qbd.templates.list", "qbd.unitOfMeasureSets.list" ], "description": "These QuickBooks queries have no iterator. They are small configuration lists in practice.", "behavior": "The list returns every matching record without cursor fields (x-daapi-pagination: none), except templates.list, which returns nextCursor null, hasMore false and remainingCount 0 because Conductor pages it. Where QuickBooks supports it, limit caps the count.", "errorCode": null, "alternatives": [ "Use the operation filters to narrow large results." ], "evidence": "qbxml_schema" }, { "id": "feature.advanced_inventory", "kind": "feature_requirement", "title": "Inventory sites need Advanced Inventory", "operationIds": [ "qbd.inventorySites.list", "qbd.inventorySites.create", "qbd.inventorySites.retrieve", "qbd.inventorySites.update", "qbd.itemSites.list", "qbd.itemSites.retrieve", "qbd.transfers.list", "qbd.transfers.create", "qbd.transfers.retrieve", "qbd.transfers.update" ], "description": "Multiple inventory sites, item sites, site transfers and site or bin fields on transactions exist only in QuickBooks Desktop Enterprise with an active Advanced Inventory subscription and multiple inventory locations turned on.", "behavior": "QuickBooks rejects the request; the API returns 422 QBD_FEATURE_NOT_ENABLED (qbXML status 3250).", "errorCode": "QBD_FEATURE_NOT_ENABLED", "alternatives": [ "Read the company preferences before offering site features.", "Omit site fields for company files without Advanced Inventory." ], "evidence": "pending_verification" }, { "id": "edition.sales_orders", "kind": "edition_requirement", "title": "Sales orders need Premier or above", "operationIds": [ "qbd.salesOrders.list", "qbd.salesOrders.create", "qbd.salesOrders.retrieve", "qbd.salesOrders.update", "qbd.salesOrders.delete" ], "description": "QuickBooks Desktop Pro has no sales orders; Premier, Accountant and Enterprise do, with sales orders turned on in Preferences.", "behavior": "QuickBooks rejects the request; the API returns 422 QBD_FEATURE_NOT_ENABLED, or QBD_REQUEST_ERROR with the native status.", "errorCode": "QBD_FEATURE_NOT_ENABLED", "alternatives": [ "Use estimates or invoices on Pro." ], "evidence": "pending_verification" }, { "id": "edition.assemblies", "kind": "edition_requirement", "title": "Inventory assemblies need Premier or above", "operationIds": [ "qbd.inventoryAssemblyItems.list", "qbd.inventoryAssemblyItems.create", "qbd.inventoryAssemblyItems.retrieve", "qbd.inventoryAssemblyItems.update", "qbd.buildAssemblies.list", "qbd.buildAssemblies.create", "qbd.buildAssemblies.retrieve", "qbd.buildAssemblies.update", "qbd.buildAssemblies.delete" ], "description": "Inventory assembly items and assembly builds are not available in QuickBooks Desktop Pro.", "behavior": "QuickBooks rejects the request; the API returns 422 QBD_FEATURE_NOT_ENABLED, or QBD_REQUEST_ERROR with the native status.", "errorCode": "QBD_FEATURE_NOT_ENABLED", "alternatives": [ "Use group items on Pro." ], "evidence": "pending_verification" }, { "id": "edition.units_of_measure", "kind": "edition_requirement", "title": "Units of measure need Premier or above", "operationIds": [ "qbd.unitOfMeasureSets.list", "qbd.unitOfMeasureSets.create", "qbd.unitOfMeasureSets.retrieve" ], "description": "Unit of measure sets exist in Premier, Accountant and Enterprise with the unit of measure preference turned on.", "behavior": "QuickBooks rejects the request; the API returns 422 QBD_FEATURE_NOT_ENABLED.", "errorCode": "QBD_FEATURE_NOT_ENABLED", "alternatives": [ "Send quantities in the base unit of the item." ], "evidence": "pending_verification" }, { "id": "edition.price_levels", "kind": "edition_requirement", "title": "Per-item price levels need Premier or above", "operationIds": [ "qbd.priceLevels.create", "qbd.priceLevels.update" ], "description": "QuickBooks Desktop Pro supports only fixed-percentage price levels; per-item price levels need Premier or above. Price levels must be turned on in Preferences.", "behavior": "QuickBooks rejects per-item price levels; the API returns 422 QBD_FEATURE_NOT_ENABLED or QBD_REQUEST_ERROR.", "errorCode": "QBD_FEATURE_NOT_ENABLED", "alternatives": [ "Use fixed-percentage price levels on Pro." ], "evidence": "pending_verification" }, { "id": "feature.multicurrency", "kind": "feature_requirement", "title": "Currencies need multicurrency turned on", "operationIds": [ "qbd.currencies.list", "qbd.currencies.create", "qbd.currencies.retrieve", "qbd.currencies.update" ], "description": "Currency records and foreign amounts exist only after the company turns on multicurrency, which QuickBooks cannot undo.", "behavior": "QuickBooks rejects the request; the API returns 422 QBD_FEATURE_NOT_ENABLED.", "errorCode": "QBD_FEATURE_NOT_ENABLED", "alternatives": [ "Check the multicurrency preference before using currency fields." ], "evidence": "pending_verification" }, { "id": "feature.payroll", "kind": "feature_requirement", "title": "Payroll data needs QuickBooks payroll", "operationIds": [ "qbd.payrollWageItems.list", "qbd.payrollWageItems.create", "qbd.payrollWageItems.retrieve", "qbd.reports.payrollDetail", "qbd.reports.payrollSummary" ], "description": "Payroll items and payroll reports depend on QuickBooks payroll being set up in the company file. Wage amounts that Intuit marks private are not returned.", "behavior": "Without payroll, queries return empty results or QBD_FEATURE_NOT_ENABLED.", "errorCode": "QBD_FEATURE_NOT_ENABLED", "alternatives": [], "evidence": "pending_verification" }, { "id": "payroll_wage_items.rates_output_only", "kind": "field_output_only", "title": "Payroll wage item rates cannot be written", "operationIds": [ "qbd.payrollWageItems.create" ], "description": "rate, ratePercent and overtimeMultiplier are elements Intuit marks private. On QuickBooks Desktop Enterprise 24 (Windows E2E run 6), wage items created with them were saved without the values: neither the add response nor a native PayrollItemWageQuery returned them. Conductor accepts these fields on create.", "behavior": "Sending them on create returns 400 UNKNOWN_PARAMETER naming the field; nothing is sent. They stay in responses and are null unless QuickBooks returns them.", "errorCode": "UNKNOWN_PARAMETER", "alternatives": [ "Create the wage item without rates, then set the rate on each employee's earnings in QuickBooks." ], "evidence": "windows_e2e" }, { "id": "personal_data", "kind": "personal_data", "title": "Social Security numbers and full card numbers are not available", "operationIds": [ "qbd.employees.list", "qbd.employees.retrieve", "qbd.employees.create", "qbd.employees.update" ], "description": "Every connection is authorized with the Web Connector personal-data preference \"not needed\", so QuickBooks never returns SSNs or full credit card numbers to the integration and the setup flow does not ask the end user for personal-data access.", "behavior": "Those fields are absent from responses and not accepted in requests.", "errorCode": null, "alternatives": [ "Collect such data outside QuickBooks if your application needs it." ], "evidence": "intuit_documentation" }, { "id": "personal_data.payroll_reports", "kind": "personal_data", "title": "Payroll reports need personal-data access", "operationIds": [ "qbd.reports.payrollDetail", "qbd.reports.payrollSummary" ], "description": "QuickBooks treats payroll reports as personal data. Connections are authorized without personal-data access, so QuickBooks Enterprise 24 rejects these reports with status 3261 until the QuickBooks Admin allows it for the application in the Integrated Applications preferences.", "behavior": "The API returns 403 QBD_INSUFFICIENT_PERMISSION with integrationCode 3261 and the steps for the QuickBooks Admin.", "errorCode": "QBD_INSUFFICIENT_PERMISSION", "alternatives": [ "Ask the QuickBooks Admin to allow personal-data access: Edit > Preferences > Integrated Applications > Company Preferences, select the application, Properties.", "Use the general summary and detail reports, which do not need personal-data access." ], "evidence": "windows_e2e" }, { "id": "region.non_us", "kind": "region", "title": "Only US editions of QuickBooks Desktop", "operationIds": [], "description": "Canadian, UK and Australian editions use different qbXML schemas (tax models, payroll, fields).", "behavior": "Resource operations return 422 QBD_REGION_UNSUPPORTED for a non-US company file; passthrough stays available at your own risk.", "errorCode": "QBD_REGION_UNSUPPORTED", "alternatives": [ "Use passthrough with the qbXML of that edition." ], "evidence": "qbxml_schema" }, { "id": "version_gated_fields", "kind": "version_gated", "title": "Fields introduced in newer qbXML versions", "operationIds": [], "description": "Each field carries the qbXML version that introduced it. QuickBooks releases older than that version do not know the field.", "behavior": "Sending a newer field to an older QuickBooks returns 422 QBD_FIELD_UNSUPPORTED_BY_VERSION with details.minimumQbxmlVersion before anything is sent.", "errorCode": "QBD_FIELD_UNSUPPORTED_BY_VERSION", "alternatives": [ "Check the connection companyFile.qbxmlVersion before sending newer fields." ], "evidence": "qbxml_schema" } ] }