How to Fix the Most Common QuickBooks Online API Errors?

QuickBooks Online (QBO) offers a robust API for developers integrating accounting functionality into their apps. However, working with this API can often result in various error codes, each requiring specific fixes. This comprehensive guide explores how to troubleshoot common QuickBooks Online API errors, their causes, and effective solutions—ensuring your integration stays seamless and reliable.

1. Error 120: Authorization Failure

Cause:

This error occurs when the connected user doesn’t have the appropriate access. Typical reasons include:

• User is not an admin.
• Admin rights have been revoked.
• User profile has been deleted from the QBO company.

Solution:

• Confirm the user’s access rights.
• Have an active admin review and adjust user permissions.
• If access is no longer required, revoke the token or disconnect the user from the app.

2. Error 500: Unsupported Operation

Cause:

This results from non-UTF-8 characters in the request payload, typically causing malformed byte sequences.

Solution:

• Ensure all requests are UTF-8 encoded.
• Use a standard library to encode request data correctly before submission.

3. Error 610: Object Not Found

Cause:

This can occur for two main reasons:

1. A referenced name list object (e.g., vendor, account, customer) is inactive.
2. A transaction has been deleted by another user.

Solution:

• Maintain a cached copy of name list objects including Id, SyncToken, DisplayName, and Active status.
• Use webhooks or change data capture (CDC) to track real-time changes.
• Before sending a transaction, check if the referenced object is still active.
• Never reference deleted transactions—track deletions with webhooks.

4. Error 2020: Required Parameter Missing

Cause:

Two primary causes:

• Missing Item.AssetAccountRef when creating an inventory item.
• Missing Line element in the transaction object.

Solution:

• Always define AssetAccountRef for inventory items.
• Ensure all required fields like Line are present when creating transactions (invoices, receipts, etc.).

5. Error 2170: Invalid Enumeration

Cause:

Attempting to manually set the TimeActivity.BillableStatus to HasBeenBilled, which QBO manages automatically.

Solution:

• Let QuickBooks handle this field. Do not manually assign HasBeenBilled.

6. Error 2500: Invalid Reference ID

Cause:

Refers to inactive name list objects with Active attribute set to false.

Solution:

• Cache and track changes to object states.
• Validate object status before submitting transaction requests.
• Use CDC or webhooks for real-time updates to object status.

7. Error 5010: Stale Object Error

Cause:

Occurs when multiple users edit the same object simultaneously, and one completes the update before the other.

Solution:

• Always fetch the latest version using syncToken before updates.
• Keep your internal database synchronized using CDC or webhooks.

8. Error 6000: Business Validation Error

Cause:

Occurs when the TotalAmt attribute is missing in BillPayment or Payment entities.

Solution:

• Ensure TotalAmt has a valid numerical value in your API requests.

9. Error 6140: Duplicate Document Number

Cause:

Occurs when your app tries to create a transaction with a DocNumber that already exists, especially if:

• CustomTxnNumbers is enabled.
• Duplicate warnings are active in user preferences.

Solution:

• Fetch Preferences.SalesFormsPrefs.CustomTxnNumbers.
• If true, apply a unique DocNumber naming pattern (e.g., appname_0001).
• If false, let QuickBooks auto-generate the number.

10. Error 6190: Invalid Company Status

Cause:

User’s subscription is inactive, expired, or has billing issues.

Solution:

• Use the SubscriptionStatus attribute in CompanyInfo to verify the subscription.
• Allow users to either wait or disconnect gracefully if the subscription becomes invalid.

11. Error 6210: Account Period Closed

Cause:

User has closed their books for a specific fiscal year, and you’re trying to update data within that closed period.

Solution:

• Ask the admin for the fiscal close date when connecting.
• Add logic to block changes to transactions within the closed period.

12. Error 6240: Duplicate Name Exists

Cause:

The DisplayName is not unique across customers, vendors, and employees.

Solution:

• Store and reference the DisplayName and Id of all relevant objects.
• Apply a naming scheme to avoid conflicts (e.g., “Jane Doe (vendor)” vs. “Jane Doe (customer)”).
• Keep your app’s database updated with changes from QuickBooks.

13. Error 6540: Deposited Transaction Cannot Be Changed

Cause:

You’re trying to modify a payment or sales receipt that’s already been deposited.

Solution:

• To make changes, edit the deposit record and unlink the associated transaction first.
• Understand and respect the deposit linkage in QBO’s workflow.

Final Thoughts on Managing QuickBooks API Errors

Handling QuickBooks Online Accounting API errors effectively involves:

• Staying up to date with object states using webhooks or CDC.
• Keeping a synchronized, local database of QuickBooks objects.
• Writing defensive code that anticipates changes in user permissions, data status, and subscription levels.

By implementing these best practices, you’ll reduce API errors and ensure a smoother integration experience for your users.

Frequently Asked Questions