> ## Documentation Index > Fetch the complete documentation index at: https://docs.qubesync.com/llms.txt > Use this file to discover all available pages before exploring further. # Set simulator faults > Beta: simulated connections don't match real QuickBooks in every case yet. Make the next sync (or every sync, for connection_error) fail in a specific way -- 404s for a real (non-simulated) connection. ## OpenAPI ````yaml /api-reference/v2/openapi.json put /connections/{connection_id}/simulator openapi: 3.1.0 info: contact: email: support@qubesync.com description: > A single generic operation surface for every curated qbXML request QuBe Sync supports, driven directly off the qbXML schema -- see the [MCP server](/mcp-server) to explore available operations interactively. **Every endpoint queues a request and returns it immediately (`201`, a `QueuedRequest`).** QuickBooks Desktop is reached through the customer's Web Connector, which polls QuBe Sync, so the answer arrives seconds to minutes later. **Pass a `webhook_url` with every request**: when QuickBooks has answered, QuBe Sync POSTs the same document to it -- `state` set, `response_json` filled in -- signed with `X-QUBE-Signature` (see the Webhooks guide). `response_json` is the `{status, data}` envelope documented on each operation: `status: "success"` with `data` derived from the qbXML `*Ret` (and `warning`, QuickBooks' code and message, when it carried the request out but warned about it), or `status: "error"` with QuickBooks' own status code and message -- a QuickBooks business error is a *successful* HTTP round trip. `links.self` returns the request on demand (for a dashboard, a retry, a script); it is not the integration path. Send an `Idempotency-Key` header with each request so a call whose answer you never got can be sent again without queueing it twice. Authentication is HTTP Basic with your app's API key as the username and a blank password. Connections themselves (creating one, onboarding, its QWC file and password) are the `/connections` endpoints; every QuickBooks operation is scoped to one of them. title: QuBe Sync API (v2) version: 2.0.0 servers: - description: v2 API url: https://qubesync.com/api/v2 - description: Local development server url: https://dev.qubesync.com/api/v2 security: - apiKey: [] tags: - description: >- Creating and managing the connection (a customer's QuickBooks company file) that every request below is queued against. See the Onboarding guide. name: Connections - description: >- Queueing qbXML you wrote yourself, listing the requests queued on a connection, and discarding one the app no longer wants. A `webhook_url` on each request is the integration path (see the Webhooks guide): the listing is for a dashboard, a script, or catching up after downtime. name: Queued Requests - description: >- Finding the record in a customer's company file that a name means, even written differently: ranked matches from QuBe Sync's index of the file's names, on realtime and simulated connections. See the Matching guide. name: Matching - description: >- Endpoints for publishing workflow definitions, starting runs, and answering a run that is waiting on a decision from your app. A workflow is one JSON statechart document; see the schema at /api/v2/workflows/schema.json. name: Workflows - name: Account Tax Line Infos - name: Accounts - name: Aging Reports - name: Alerts - name: Ar Refund Credit Cards - name: Bar Codes - name: Bill Payment Checks - name: Bill Payment Credit Cards - name: Bill To Pays - name: Billing Rates - name: Bills - name: Budget Summary Reports - name: Build Assemblies - name: Charges - name: Checks - name: Classes - name: Cleared Statuses - name: Companies - name: Company Activities - name: Credit Card Charges - name: Credit Card Credits - name: Credit Memos - name: Currencies - name: Custom Detail Reports - name: Custom Summary Reports - name: Customer Msgs - name: Customer Types - name: Customers - name: Data Event Recovery Infos - name: Data Ext Defs - name: Data Exts - name: Date Driven Terms - name: Deposits - name: Employee Defaults - name: Employees - name: Entities - name: Estimates - name: Form1099 Category Account Mappings - name: General Detail Reports - name: General Summary Reports - name: Hosts - name: Inventory Adjustments - name: Inventory Sites - name: Invoices - name: Item Assemblies Can Builds - name: Item Discounts - name: Item Fixed Assets - name: Item Groups - name: Item Inventories - name: Item Inventory Assemblies - name: Item Non Inventories - name: Item Other Charges - name: Item Payments - name: Item Receipts - name: Item Sales Tax Groups - name: Item Sales Taxes - name: Item Services - name: Item Sites - name: Item Subtotals - name: Items - name: Job Reports - name: Job Types - name: Journal Entries - name: Leads - name: List Deleteds - name: List Displays - name: List Merge - name: Lists - name: Other Names - name: Paychecks - name: Payment Methods - name: Payments - name: Payroll Detail Reports - name: Payroll Item Additions - name: Payroll Item Company Contributions - name: Payroll Item Deductions - name: Payroll Item Direct Deposits - name: Payroll Item Non Wages - name: Payroll Item Taxes - name: Payroll Item Wages - name: Payroll Item Workers Compensations - name: Payroll Items - name: Payroll Last Periods - name: Payroll Liability Adjustments - name: Payroll Liability Checks - name: Payroll Prior Payments - name: Payroll Summary Reports - name: Payroll Year To Date Adjustments - name: Preferences - name: Price Levels - name: Purchase Orders - name: Qb Command Exec - name: Receive Payment To Deposits - name: Receive Payments - name: Sales Orders - name: Sales Receipts - name: Sales Reps - name: Sales Tax Codes - name: Sales Tax Payables - name: Sales Tax Payment Checks - name: Sales Tax Return Lines - name: Sales Tax Returns - name: Ship Methods - name: Special Accounts - name: Special Items - name: Standard Terms - name: Templates - name: Terms - name: Time Reports - name: Time Trackings - name: To Dos - name: Transactions - name: Transfer Inventories - name: Transfers - name: Txn Deleteds - name: Txn Displays - name: Txn Void - name: Txns - name: Unit Of Measure Sets - name: Vehicle Mileages - name: Vehicles - name: Vendor Credits - name: Vendor Types - name: Vendors - name: Workers Comp Codes paths: /connections/{connection_id}/simulator: put: tags: - Connections summary: Set simulator faults description: >- Beta: simulated connections don't match real QuickBooks in every case yet. Make the next sync (or every sync, for connection_error) fail in a specific way -- 404s for a real (non-simulated) connection. operationId: setSimulatorFaults parameters: - description: The connection to act on. in: path name: connection_id required: true schema: format: uuid type: string requestBody: content: application/json: schema: properties: faults: properties: connection_error: description: >- The Web Connector cannot reach QuickBooks, reported right after it authenticates and before it asks for any request, as the real one reports it: `qb_closed` is QuickBooks closed for an app authorized only while it runs (hresult 0x8004041D), `company_file_missing` the Web Connector failing to start QuickBooks on the stored file (0x80040408, "Could not start QuickBooks."). Sticky until cleared (every sync fails with it) -- set to null/omit to clear. enum: - qb_closed - company_file_missing - modal_dialog - company_file_mismatch - unexpected nullable: true type: string latency_ms: description: >- How long the fake QuickBooks "thinks" before each answer. type: integer next_lost_response: description: >- The next request that changes the company file (an add, mod, delete, void or merge) is applied but never answered: the Web Connector session dies before it can say, as a crashed connector's does. The request ends `timed_out`, and a workflow that sent it settles it (see the workflow guide). Queries and reports before it are answered normally and leave the fault armed, since a lost query is simply asked again. Consumed once, by that write. type: boolean next_response_error: description: >- The next request is answered with an hresult instead of qbXML (a malformed-XML style failure). The shorthand "xml_error", or `{"hresult": "...", "message": "..."}`. Consumed once. It ends as a real one does: a connection error's message (a dialog open, QuickBooks closed) leaves the request `retryable`; any other ends a write `error` with `error_type` `outcome_unknown`, and a query `unexpected_error`. oneOf: - enum: - xml_error type: string - properties: hresult: type: string message: type: string type: object next_response_too_large: description: >- The next request is applied to the company file, and its answer is over QuBe Sync's size limit on one answer: the request ends `error` with `error.error_type` `response_too_large` and no `response_xml`, as a real answer that large does, and a workflow that sent it sees `no_response` with reason `too_large`. Sandbox companies are too small to reach the limit otherwise. Consumed once. type: boolean next_status: description: >- The next request's *Rs carries this status instead of being processed. Consumed once. properties: code: example: 3100 type: integer message: type: string type: object stalled: description: >- The connection stalls, so you can test your `connection.stalled` and `connection.resumed` handling: the value is the `stall_reason` it's sent with. While it's set the Web Connector doesn't run, so your requests wait, as on a real stall; once one of them is waiting, `connection.stalled` is sent within seconds instead of after the usual grace. Sticky until cleared: set to null or omit it to send `connection.resumed` and have the waiting requests answered. enum: - not_checking_in - quickbooks_unavailable nullable: true type: string type: object type: object required: false responses: '200': content: application/json: schema: properties: data: properties: company: description: A summary of the fake company file's contents. properties: company_name: type: string lists: additionalProperties: type: integer description: >- Record counts by list type, e.g. `{"Customer": 3}`. type: object open_iterators: type: integer transactions: additionalProperties: type: integer description: Record counts by transaction type. type: object type: object connection_id: format: uuid type: string faults: additionalProperties: true description: >- The faults currently set (see the requestBody of "Set simulator faults" for what each key accepts). type: object links: properties: connection: format: uri type: string ui: format: uri type: string type: object type: object type: object description: Faults updated '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': content: application/json: schema: $ref: '#/components/schemas/Error' description: Not a simulated connection security: - apiKey: [] components: responses: BadRequest: content: application/json: example: errors: 'unknown parameter: "emial"' schema: $ref: '#/components/schemas/Error' description: >- A parameter the operation does not take, or a value it cannot use. Nothing was queued. Unauthorized: content: text/plain: example: Unauthorized schema: type: string description: >- No usable API key. The key is Basic auth, so the answer is the challenge, with the plain-text body Unauthorized rather than JSON. headers: WWW-Authenticate: schema: example: Basic realm="Application" type: string NotFound: content: application/json: example: errors: detail: Not Found schema: $ref: '#/components/schemas/Error' description: Nothing by that id, or it belongs to another app. schemas: Error: description: >- What a refused request answers with. The one key is errors, and its shape says what went wrong: a sentence when the endpoint explains the refusal in words (a parameter the operation does not take, a key already taken, a run that has already ended); an object with detail, and a code when there is one, when the request named nothing that exists or may not do what it asked (402, 403, 404, and a CLI session's 401), or an answer to a run's question was refused (the decisions endpoint's 400, 409 and 422, which always carry a code to branch on); an object of fields, each a list of messages, when a record failed validation and nothing was saved; a list of {path, message} problems when a submitted document or input fails validation. A request without a usable API key gets a 401 Basic challenge with the plain-text body Unauthorized, not JSON. properties: errors: oneOf: - example: 'unknown parameter: "emial"' title: A sentence type: string - properties: code: example: read_only_session type: string detail: example: Not Found type: string required: - detail title: Detail and code type: object - additionalProperties: items: type: string type: array example: webhook_url: - may not contain a username or password title: Field by field type: object - items: properties: message: example: is required type: string path: example: input.customer type: string required: - path - message type: object title: Located problems type: array required: - errors type: object securitySchemes: apiKey: description: Use your app's API key as the username, and leave the password blank scheme: basic type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.