Top QuickBooks Online API Errors and How to Handle Them

How to Handle Frequently Returned QuickBooks Online API Error Messages

The developer relations team monitors errors that are returned frequently for apps that use the QuickBooks Online API for a wide variety of use cases.  We have identified the top errors where a small code change can make a big difference. In this article, we’ll go through a list of these error responses and provide some recommendations and best practices for handling them from within your application. Reducing your app’s errors helps reduce failed customer interactions in your app, setting you well on your way to delighting your customers.

Frequently Returned Errors

No	HTTP-Status	Error-Code	Error-Message	Error-Detail
1.	400	6240	Duplicate Name Exists Error	The name supplied already exists: Another customer is already using this name. Please use a different name.
2.	400	6210	Duplicate Document Number Error	Duplicate Document Number Error: You must specify a different number. This number has already been used.
3	400	610	Object Not Found	Object Not Found: Something you’re trying to use has been made inactive. Check the fields with accounts.
4	401	120	Authorization Failure	AuthorizationFailure: –11014-You do not have access to use QuickBooks Online Plus.
5	400	6190	Invalid Company Status	Subscription period has ended or been canceled, or there was a billing problem: You can’t add data to QuickBooks Online Plus because your trial or subscription period ended
6	400	610	Object Not Found	Object Not Found: Another user has deleted this transaction.
7	400	2500	Invalid Reference Id	Invalid Reference Id: Something you’re trying to use has been made inactive. Check the fields with accounts.
8	400	6540	Deposited Transaction cannot be changed	This transaction has been deposited. If you want to change or delete it, you must first edit the deposit it appears on and remove it.
9	400	2170	Invalid Enumeration	Invalid Enumeration: HAS_BEEN_BILLED
10	400	6000	A business validation error has occurred while processing your request	Business Validation Error: You must set a transaction amount.
11	400	6210	Account Period Closed	The account period has closed and the account books cannot be updated through the QBO Services API. Please use the QBO website to make these changes.
12	400	500	Unsupported Operation	Operation com.sun.org.apache.xerces.internal.impl.io.MalformedByteSequenceException: Invalid byte 1 of 1-byte UTF-8 sequence. is not supported.
13	400	2020	Required param missing	Required parameter: Line is missing in the request.
14	400	2020	Required param missing	Required parameter: An inventory asset account is required if you are tracking inventory quantities for this product.
15	400	5010	Stale Object Error	Stale Object Error: You and {other user name} were working on this at the same time. {other user name} finished before you did, so your work was not saved.

Recommendations

As you can see from the above list, some of these errors could have been handled better or even been prevented in the first place. Here are some recommendations for preventing or handling these error responses.

ERROR NO – 1

HTTP Status	Error Code	Error Message	Error Detail
400	6240	Duplicate Name Exists Error	The name supplied already exists.

Description –

Error Handling/Prevention –
You can fetch the Id and name attributes of all customer, vendor and employee records from the target QuickBooks Online account and persist them in your application’s database. You can keep this database up to date by using ‘Change Data Capture'(CDC) or webhooks, or both. Before creating any new customer, vendor or employee, your app should  check the database to see if the name already exists.

Based on the end user’s preference, you can either refer to the existing customer or create a new customer/vendor/employee by adding any meaningful characters to make the name unique. We see our users often using names like “John Smith (Vendor)” to easily distinguish their contacts.

ERROR NO – 2

HTTP Status	Error Code	Error Message	Error Detail
400	6210	Duplicate Document Number Error	Duplicate Document Number Error : You must specify a different number. This number has already been used.

Description – QuickBooks Online provides a transaction (invoice, bill, etc.) attribute called ‘DocNumber’, which acts as a transaction reference.

By default, QuickBooks Online generates a unique DocNumber for each transaction. From the ‘Company Settings’ window of the QBO UI, QBO users can enable the ‘Custom transaction numbers’ feature, which allows them to enter a customized alphanumeric DocNumber. End users can also enable the ‘Warn if duplicate check/bill number is used’ feature which warns a UI user when a duplicate DocNumber is used and creates the transaction only if the end-user accepts the warning. Unfortunately, similar behavior doesn’t exist in corresponding transaction APIs such as Invoice, and Bill.

In summary, this error happens only when the following three conditions are true:

-‘Custom transaction numbers’ feature is enabled
-‘Warn if duplicate check/bill number is used’ is enabled in QBO UI
-Developers pass ‘numeric’ or ‘alpha-numeric’ string as docNumber

Error Handling/Prevention –
The app should call the ‘Preference’ API to check if ‘Custom transaction numbers’ is allowed in the target QuickBooks Online company. Preference entity returns an attribute called ‘CustomTxnNumbers’ which can be used for this check. If it is enabled, then when creating any transaction, you should enter some unique DocNumber pattern such as ‘your_app_name-‘+serial_number. This will prevent DocNumber collisions with transactions manually entered by the user or by a different app.

ERROR NO – 3

HTTP Status	Error Code	Error Message	Error Detail
400	610	Object Not Found	Object Not Found : Something you’re trying to use has been made inactive. Check the fields with accounts.

Description – This error is returned when we pass an inactive object (usually name entities like Customer, Vendor, or Account) reference to create a dependent entity such as Invoice. In QuickBooks, name list entities can’t be deleted permanently. Name entity objects can be deleted from the UI or by setting the “active” attribute to “false” using the API.

Error Handling/Prevention –
Before referencing any object we should check that it is not in an inactive state. Checking invalid state before every other call, though, would increase the number of API calls unnecessarily. You might want to cache the Id, SyncToken, Name and Active state of all the name list entities in your application’s DB while setting up the connection with the target QuickBooks Online account for the very first time. Then you should leverage the Webhooks or the Change Data Capture APIs to monitor changes to the referenced objects. If you detect a change, then you should capture the changed data and update your application’s cache so that we can use the latest reference data when creating new dependent objects such as Invoice.

ERROR NO – 4

HTTP Status	Error Code	Error Message	Error Detail
401	120	Authorization Failure	AuthorizationFailure: –11014-You do not have access to use QuickBooks Online Plus.

Description – This error suggests that the company admin who connected his QuickBooks Online account with your app is either not an admin anymore or has been removed from that particular QuickBooks Online account.

Error Handling/Prevention –
There is no way to make the existing OAuth tokens work to make any API call against the target company. If we get this error, then we should stop calling any further APIs on this account and consider this connection as disconnected.
You might want to reach out to the old QuickBooks Online Account owner to check if he or the new owner still needs your app or wants to close the connection officially.

ERROR NO – 5

HTTP Status	Error Code	Error Message	Error Detail
400	6190	Invalid Company Status	Subscription period has ended or been canceled, or there was a billing problem: You can’t add data to QuickBooks Online Plus because your trial or subscription period has ended.

Description – This error message indicates that the target QBO company is invalid and is in unpaid status.

Error Handling/Prevention –
If you get this error message, then your app should stop calling any further APIs against the target QuickBooks Account. You might want to reach out to the QuickBooks Online Account owner to take any further steps such as disconnecting the connection or waiting for the connection to be activated.

ERROR NO – 6

HTTP Status	Error Code	Error Message	Error Detail
400	610	Object Not Found	Object Not Found: Another user has deleted this transaction.

Description – This error message is very similar to ErrorNo-3 above.
We receive this error when referring to a deleted transaction in an API URL or payload.

Error Handling/Prevention –
To track deleted transactions, please leverage the WebHook or Change Data Capture APIs.

ERROR NO – 7

HTTP Status	Error Code	Error Message	Error Detail
400	2500	Invalid Reference Id	Invalid Reference Id: Something you’re trying to use has been made inactive. Check the fields with accounts.

Description – This error message is also similar to ErrorNo-3 above.
We receive this error when referring to inactive name list entities such as Account.

Error Handling/Prevention –

To track deleted transactions, please leverage the WebHook or Change Data Capture APIs.

ERROR NO – 8

HTTP Status	Error Code	Error Message	Error Detail
400	6540	Deposited Transaction cannot be changed	This transaction has been deposited. If you want to change or delete it, you must first edit the deposit it appears on and remove it.

Description – In QuickBooks Online, we receive payment from customers using the Payment or SalesReceipt endpoints, and capture the money in the Un-deposited Fund account. We use the  Deposit API to move the money from the Un-deposited Fund to the desired Bank Account. While creating the Deposit entity, we link the Payment or SalesReceipt transaction to the deposit entry.

Error Handling/Prevention –
As the error message suggests, we can’t change a transaction(Payment/SalesReceipt) which is already deposited, i.e., linked with a deposit entry.

ERROR NO – 9

HTTP Status	Error Code	Error Message	Error Detail
400	6540	Invalid Enumeration	Invalid Enumeration : HAS_BEEN_BILLED

Description – HasBeenBilled should not be an updatable status. A TimeActivity becomes HasBeenBilled once it is applied to an invoice as a LinkedTxn.

Error Handling/Prevention –
We shouldn’t update any TimeActivity to set its status as HasBeenBilled.

ERROR NO – 10

HTTP Status	Error Code	Error Message	Error Detail
400	6000	A business validation error has occurred while processing your request	Business Validation Error: You must set a transaction amount.

Description – BillPayment and Payment APIs have a required attribute called TotalAmt, which should always have a valid transaction amount.

Error Handling/Prevention –
When creating any BillPayment or Payment entry, make sure that TotalAmt is set with a valid transaction amount.

ERROR NO – 11

HTTP Status	Error Code	Error Message	Error Detail
400	6210	Account Period Closed	The account period has closed and the account books cannot be updated through the QBO Services API. Please use the QBO website to make these changes.

Description – Closing the books normally refers to the accounting process of zeroing out your income and expense accounts and recording the company’s net profit or loss in the Balance-Sheet. At the end of the year, QuickBooks Online automatically closes out your income and expense accounts and rolls up your net profit or loss into your Retained Earnings account. The main purpose of officially closing the books is to protect transactions in previous periods from being changed.

Error Handling/Prevention –
Unfortunately, there is no programmatic way to know the Account Period Close Date. So, when setting up a new connection, ask for the Account Period Close Date from the QBO company admin who would subscribe to your app. Since you can’t make changes to transactions that fall into the closed Account Period, you can refer to the previous Account Period Close Date before modifying or deleting any transaction.

ERROR NO – 12

HTTP Status	Error Code	Error Message	Error Detail
400	500	Unsupported Operation	Operation com.sun.org.apache.xerces.internal.impl.io.MalformedByteSequenceException: Invalid byte 1 of 1-byte UTF-8 sequence. is not supported.

Description – This error message indicates that there are some non UTF-8 characters present in the payload.

Error Handling/Prevention –
You can use any standard library or functions to set UTF-8 encoding to your API payload.

ERROR NO – 13

HTTP Status	Error Code	Error Message	Error Detail
400	2020	Required Param Missing	Required parameter Line is missing in the request

Description – QuickBooks Online expects at least one Line item when creating transaction entities (such as  Invoice, Bill, BillPayment).

Error Handling/Prevention –
Your app should pass a Line attribute and all other required attributes when creating objects using the API. For details, please refer to the individual API documentation here: https://developer.intuit.com/docs/api/accounting.

ERROR NO – 14

HTTP Status	Error Code	Error Message	Error Detail
400	2020	Required Param Missing	Required parameter: An inventory asset account is required if you are tracking inventory quantities for this product, and it is missing in the request

Description – Inventory Asset account tracks the current value of the inventory item. It is a mandatory attribute of any Inventory type item.

Error Handling/Prevention –
The application should pass an Inventory Asset Account reference while creating Inventory Item objects using the API. For details, please refer to the API reference documentation here: https://developer.intuit.com/docs/api/accounting/item.

ERROR NO – 15

HTTP Status	Error Code	Error Message	Error Detail
400	5010	Stale Object Error	Stale Object Error : You and {other user name} were working on this at the same time. {other user name} finished before you did, so your work was not saved.

Description – This error means that while attempting some modification operation (update/delete), you are not working on the latest version of the object.

Error Handling/Prevention –
Before performing any update/delete operation, retrieve the latest version of the object. In the response payload, you’ll get the latest sycnToken value which you should pass to perform any UPDATE or DELETE operation. Since this approach adds one extra getById API call, it is better to avoid when you have a large number of update/delete operations. To optimize this operation, please consider storing the objectIds, type, and syncToken in your application’s database. That way you can leverage the Change Data Capture or Webhooks APIs to detect the changed objects. If an object is changed, call the getById endpoint to fetch the latest syncToken.

Conclusion

In this article, we shared the details of the top 15 issues that are frequently sent or received by developers. If you face any other major issues which are not addressed in this list, please post your questions in the DevSupport community page here: https://help.developer.intuit.com/s/

We’ll continue to monitor API usage patterns and most frequently returned error messages, and apply these learnings to increase the quality of the QuickBooks Online APIs.

Best Wishes,

Manas Mukherjee
Intuit Developer Group