Fix common QuickBooks Online Accounting API errors

If you or your app users ever see an error, look up the error code to identify the issue.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
   "Fault":
   {
      "Error": [
      {
         "Message": "<message>",
         "Detail": "<detail>",
         "code": "<code>",
         "element": ""
      }],
      "type": "ValidationFault"
   },
   "time": "2017-09-29T09:17:31.892-07:00"
}
120: Authorization Failure
Error code Message Detail
120 Authorization Failure : –11014-You do not have access to use QuickBooks Online Plus.
Common cause

One of the following conditions applies to individual who connected their QuickBooks Online company to your app:


Solution

Fix or disconnect the connection.

Reach out to a current admin user for the QuickBooks Online company. Ask if they still need to connect to your app.

If they don’t, you can revoke their access.

500: Unsupported Operation
Error code Message Detail
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.
Common cause

There are non-UTF-8 characters in your request payload.


Solution

Use any standard library or function to set UTF-8 encoding for your request payload.

610: Object Not Found

There are two possible reasons for error 610. Check the detail field in the response payload to see which one applies:

Error code Message Detail
610 Object Not Found Object Not Found: Something you’re trying to use has been made inactive. Check the fields with accounts.
Common cause

This is usually caused by references to inactive name list objects (i.e. a customer, vendor, account, etc) in transaction requests.

For instance, the customer object referenced in an invoice should have an Invoice.CustomerRef element. It’s likely the Customer.Active attribute is set to false.


Solution

To prevent this error:

Error code Message Detail
610 Object Not Found Object Not Found : Another user has deleted this transaction.
Common cause

This is usually caused by references to deleted transaction objects in requests.


Solution

When users delete transactions in QuickBooks, they’re permanently removed.

However, name list objects, such as customers or vendors, don’t get deleted. They’re simply marked “inactive.”

Use webhooks or the change data capture operation to keep track of deleted and added transactions.

2020: Required Param Missing

There are two possible reasons for error 2020. Check the detail field in the response payload to see which one applies:

Error code Message Detail
2020 Required Param Missing Required parameter is missing in the request. An inventory assetaccount is required if you are tracking inventory quantities for this product.
Common cause

The Item.AssetAccountRef isn’t set for an inventory object in your request.


Solution

You must include the Item.AssetAccountRef when creating an inventory item. Learn more about the Item entity.

Error code Message Detail
2020 Required Param Missing Required parameter Line is missing in the request.
Common cause

A Line element is missing from the transaction object’s request payload.


Solution

Learn more about required parameters for transaction (invoices, sales receipt, etc) API entities.

2170: Invalid Enumeration
Error code Message Detail
2170 Invalid Enumeration Invalid Enumeration : HAS_BEEN_BILLED
Common cause

Apps can’t directly set the TimeActivity.BillableStatus attribute to HasBeenBilled.

QuickBooks automatically sets the TimeActivity entity’s billable status to HasBeenBilled by QuickBooks (not by a user’s action) when your app links it to an invoice object via Invoice.LinkedTxn.


Solution

Don’t manually set TimeActivity.BillableStatus to HasBeenBilled. Let the system handle it.

2500: Invalid Reference Id
Error code Message Detail
2500 Invalid Reference Id Invalid Reference Id : Something you’re trying to use has been made inactive. Check the fields with accounts.
Common cause

This is usually caused by references to inactive name list objects (i.e. a customer, vendor, account, etc) in requests.

The Active attribute is likely set to false for the target name list object.


Solution

To prevent this error:

5010: Stale Object Error
Error code Message Detail
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. Entity=<entity name>
Common cause

This usually means you’re working with a stale object.


Solution

Always work with the latest version of objects. An object’s version is stored in its syncToken attribute.

Performing read operations before updates makes sure you’re always getting the latest data if you aren’t using webhooks or the change data capture operation.

Learn more about syncTokens.

6000: A business validation error has occurred while processing your request
Error code Message Detail
6000 A business validation error has occurred while processing your request Business Validation Error: You must set a transaction amount.
Common cause

The TotalAmt attribute isn’t set for the BillPayment or Payment enitities in your request. The TotalAmt attribute is required.


Solution

Make sure the TotalAmt attribute has a valid transaction amount in requests.

6140: Duplicate Doc Num Error
Error code Message Detail
6140 Duplicate DocNum Error Duplicate Document Number Error : You must specify a different number. This number has already been used.
Common cause

When you create a transaction, your app sends a string in DocNumber that happens to duplicate the number in an existing transaction object, and these conditions are met:


Solution

Fetch and check the Preferences.SalesFormsPrefs.CustomTxnNumbers attribute before creating any transactions.

This prevents DocNumber duplications when users or other apps manually enter transactions that utilize QuickBooks data.

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

The target user’s QuickBooks Online subscription state is preventing the operation.

For example, your app may be trying to use a write operation, but based on the user’s subscription state, it can only do read-only operations.


Solution

Use the SubscriptionStatus attribute of the CompanyInfo entity to check the company’s subscription state.

Design your app so it can handle changes to subscription states `QuickBooks Online subscription state. It’s especially important to anticipate billing-driven issues. Consider whether your app can wait for subscriptions to become valid again, or letting users disconnect from your app if they end their QuickBooks subscription.

6210: Account Period Closed
Error code Message Detail
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.
Common cause

In QuickBooks Online, many users automatically close the books at the end of their fiscal year.

This error usually occurs when you try to modify a transaction within this closed accounting period.


Solution

If a user automatically closes their books in QuickBooks Online, transactions within the closed year time period can’t be modified.

Currently, it’s not possible to check the end of the fiscal year, or if a user’s books are closed, via the QuickBooks Online Accounting API.

It’s also not possible to change the “close the books” settings via the QuickBooks Online Accounting API.

To anticipate this:

6240: Duplicate Name Exists Error
Error code Message Detail
6240 Duplicate Name Exists Error The name supplied already exists. Another customer, vendor or employee is already using this name. Please use a different name.
Common cause

The DisplayName attribute must be unique across all customer, vendor, and employee objects.


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

The target transaction is linked to a deposit object via the deposit’s Deposit.Line.LinkedTxn attribute.

QuickBooks users record customer payments using payments (against an invoice) or sales receipts (if payment is received at the time of purchase). Learn more about sales receipts and invoices.

Payments may go to what’s known as an Undeposited Funds account. Users use a deposit to move money from the Undeposited Funds Account to another bank account. This subsequent deposit object links back to the original payment or salesReceipt object.


Solution

You can’t modify transactions (payments or sales receipts) that are already deposited and linked to a deposit.

Learn more about bank deposits in QuickBooks Online.