QuickBooks Connector
QuickBooks Connector
Breadcrumbs

API Errors

1.1 Quick Diagnostic: Read the Status Description

Every QB record's Status_Description__c field contains the raw API error when a sync fails. The structure maps directly to QBO API fault responses:

Fault Type: ValidationFault
Code: 6240
Message: Duplicate Name Exists Error
Detail: The name supplied already exists : <Name>

1.2 Common QBO API Error Codes in This Integration

Code

Message

Typical Trigger in This App

Resolution

120

Authorization Failure

Token expired or revoked between batch runs

Re-authorize via Connect to QuickBooks

610

Object Not Found

Referenced ItemRef, CustomerRef, or AccountRef points to a deleted/inactive QBO entity

Verify the referenced entity is active in QBO; update the reference on the QB record

2020

Required Param Missing

A required QBO field was not mapped (e.g., DisplayName for Customer is blank)

Check the field mapping and ensure the source SF field has a value

5010

Stale Object Error

Concurrent update — Quickbooks_SyncToken__c is out of date

Run Sync from QuickBooks to refresh the SyncToken, then retry the outbound sync

6140

Duplicate Doc Num Error

DocNumber on invoice already exists in QBO

Ensure DocNumber values are unique; clear the field to let QBO auto-assign

6210

Account Period Closed

Attempting to create/update a transaction in a closed accounting period

Change the transaction date to the current open period

6240

Duplicate Name Exists Error

DisplayName (Customer/Vendor) or Name (Account/Product) already exists in QBO

Use the auto-match flow to link the existing QBO record instead of creating a new one

6540

Deposited Transaction Error

Trying to update an invoice/payment that has been deposited

Void the deposit in QBO first, or do not sync changes to deposited transactions

1.3 401 Errors — Token Expiry Mid-Batch

Symptom: A batch starts successfully but individual records fail with 401 or 'Credentials Not Found' in Status_Description__c.

Cause: Access tokens expire after 1 hour. If a large batch runs longer than 1 hour, later records in the batch will fail because the access token used at batch start has expired. The connector does not automatically refresh tokens mid-batch.

Fix:

  1. Reduce the BatchSize setting in Quickbooks_Common_Settings__c so each batch execution completes faster.

  2. Ensure BatchRefreshTokenUpdate is running on schedule — this keeps refresh tokens current so the next batch invocation gets a fresh access token.

  3. Failed records will have Status__c = 'Failed' and Process_via_Batch__c = false — set Process_via_Batch__c = true to re-queue them after the token is refreshed.

1.4 HTTP 429 — Rate Limit Exceeded

Symptom: Sync failures with 429 in Status_Description__c during bulk operations.

Cause: QBO enforces 40 API requests per minute per realm ID. Running multiple concurrent batch jobs against the same company can breach this limit.

Fix:

  1. Do not run multiple full-pull batches for the same company simultaneously.

  2. Reduce BatchSize to slow the throughput rate.

  3. Re-queue failed records after a few minutes — they will be picked up on the next batch run.