QuickBooks Online Common Errors

Overview

This page details some of the most common QuickBooks Online Errors that our users might encounter when syncing invoices or payments.

Any QuickBooks syncing errors displayed in the ServiceMinder system originate from QuickBooks. We always recommend referring to their documentation in addition to ours when trying to resolve syncing errors.

Because QuickBooks is very protective over the data in their system, there is very little that we are able to see and do on the serviceminder side. That usually means we cannot fix something directly for you, or even see much detail about what has gone wrong. However, we have assembled some of the more common QuickBooks errors our Users have encountered. 

---

Settings and Navigation

To first diagnose the issue, you need to view what the Error says. You can find a list of QuickBooks Errors in the navigation menu under Snapshots. If you don't have any errors, this will not show or you may see a count of 0. 

Clicking on the QuickBooks Errors snapshot will take you to the Publishing Status / Publishing Errors page. This grid provides details about the failed sync event, including:

• The time of publishing
• The time of the error
• The type of sync (invoice or payment)
• The contact name
• The error that was sent to us from Quickbooks
• Retry and Clear action buttons

---

QBO Sync for Payments and Write-Offs

If you have the Import Payments box checked in the QuickBooks integration configuration, payments or write-offs that are added directly in QuickBooks Online (outside of ServiceMinder) will sync into ServiceMinder as payments.

If these payments were added in error and are not valid, you can delete them in ServiceMinder with the proper permissions granted. A Brand Administrator can also delete them, or you may submit a Support ticket and our team can remove them for you.

After deleting the incorrect payments in ServiceMinder, you can write off the invoices within ServiceMinder as needed. However, keep in mind that writing off invoices in ServiceMinder may affect your QBO records if activity has already occurred on the QuickBooks side. From within ServiceMinder, the correct process is to delete the incorrect payments and then write off the invoices.

---

Common QuickBooks Errors

Invalid Reference ID: Categories Cannot Be Used in Transactions

Error message:

• Validation Exception was thrown. Details: Invalid Reference Id: Categories cannot be used in transactions
• Invalid Reference Id: An item in this transaction is set up as a category instead of a product or service.

Cause:
QuickBooks Online stores Products/Services and Categories in the same internal table. If a Category and a Product/Service share the same name, QBO may return the Category instead of the actual item when ServiceMinder sends an invoice or payment.
QBO does not allow Categories to be used as line items, which causes the sync to fail.

Resolution:

1. Identify the line item(s) on the failed invoice in ServiceMinder.
2. In QBO, check if any Category shares the same name as that Product/Service.
3. Rename the Category so that only the Product/Service uses that name.
4. Return to ServiceMinder and click Retry on the error.

Tax Rate Mapping Issues

Error message:

• Unable to find tax rate with name ‘XXX’

Cause:
A tax rate used in ServiceMinder is not mapped to the corresponding tax rate in QBO. Sometimes QBO does not return its tax rate list to ServiceMinder, making the dropdown appear blank.

Resolution:

1. In ServiceMinder, go to Control Panel > Invoices > Manage Tax Rates.
2. Edit the tax rate listed in the error and choose the matching QBO rate from the QuickBooks Tax Rate Name dropdown.
3. If the dropdown is empty, create a dummy invoice in QBO, save it, and try again. (This forces QBO to re-publish its tax rate table.)
4. Return to the QuickBooks Errors page and click Retry on both the invoice and payment.

Closed Accounting Period

Error message:

• Validation Exception: The account period has closed and the account books cannot be updated through the QBO Services API.

Cause:
The transaction date in ServiceMinder falls within a closed period in QBO. Closed periods prevent external systems (including ServiceMinder) from modifying transactions.

Resolution:

1. Consult your accountant before making changes.
2. In QBO, reopen the accounting period or adjust the closing date.
3. Click Retry in ServiceMinder to reattempt the sync.
4. If reopening the period is not allowed, make the necessary edits directly in QBO.

Duplicate Document Number

Error message:

• Validation Exception: This number has already been used.

• Duplicate Document Number

Cause:
QBO requires unique document numbers across invoices, credit memos, and write-offs. If your historical QBO numbering overlaps with numbers generated in ServiceMinder, a collision may occur.

Resolution:

1. In QBO, search for the duplicate number across all transactions, not just invoices.
2. Update the duplicate number in QBO.
3. Return to ServiceMinder and click Retry on the error.
4. To reduce future conflicts, enable: Control Panel > Integrations > Accounting > Add Contact ID to Names
   (Helps avoid numbering collisions.)

Unauthorized – 401 Error

Error message:

• Unauthorized – 401

Cause:
The QBO authentication token is invalid. This is usually due to a password change, expired login, integration timeout, or the connecting QBO user being deactivated.

Resolution:

1. Go to Control Panel > Integrations > QuickBooks.
2. Click Disconnect.
3. Reconnect using valid QBO login credentials.
4. Retry failed syncs.

Unable to Locate / Transaction Dependency Errors

Error message:

• Unable to locate
• TxnID cannot be linked

Cause:
A payment cannot sync because the invoice has not synced yet, or the invoice was deleted/renamed in QBO.

Resolution:

1. Resolve the invoice-related error first and ensure the invoice syncs.
2. Retry the payment sync.
3. If necessary, apply the payment temporarily to the client account balance, let it sync, then reassign it in both systems.

Object Reference Not Set to an Instance of an Object

Error message:

• Object Reference Not Set to an Instance of an Object
  

Cause:
A temporary connection issue prevented ServiceMinder from communicating with QBO.

Resolution:
Click Retry.
If it reoccurs, disconnect and reconnect the integration, then retry the queue.

Transaction Already Deposited

Error message:

• This transaction has been deposited

Cause:
The payment already exists within a finalized bank deposit in QBO.

Resolution:

1. Click Retry in ServiceMinder—this clears the error in many cases.
2. If it persists, correct the deposit in QBO and retry the sync.

General QuickBooks API Errors

Error messages:

• Critical error during sync: QueryProcessingError: null

• An unknown error occurred during the sync

• Unable to connect to QuickBooks Online

Cause:
Temporary outages or instability in the QBO API.

Resolution:

1. Wait 30 seconds to several minutes.
2. Click Retry.
3. If errors persist, disconnect/reconnect the QBO integration.

Client Already Exists / Client Not Found in QBO

Error message:

• Client already exists in QuickBooks
• Client is not in sync
• Missing client in QuickBooks

Cause:
Client naming mismatch, duplicate client, or the client has not yet synced.

Resolution:

1. Search QBO for similar client names.
2. Rename the SM client temporarily to force sync.
3. If it already exists, merge clients in QBO.
4. Retry the invoice or payment afterward.

Product or Service Not Found / Duplicate / Mismatched Types

Cause:

• Duplicate product or service names
• Item already mapped to another SM item
• Inventory item type conflicts (cannot change type)
• QBO returned the wrong item due to naming similarity

Resolution:

1. Confirm item names in QBO are unique.
2. If duplicates exist, rename or merge.
3. Recreate inventory items if the type is wrong.
4. Retry the sync.

---

FAQs

What do I do if I don't see the specific error code on this list?

1. Google the QuickBooks error to learn more - sometimes that is what we have to do. 
2. Ask your accountant/bookkeeper for assistance. 
3. Or you can send a Support ticket to see if there are ways we can assist. However, we do not have access to your QBO account, therefore, our help is extremely limited. 

If you have more questions, please review Common QuickBooks Questions.