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" } |
Error code | Message | Detail |
120 | Authorization Failure | : –11014-You do not have access to use QuickBooks Online Plus. |
One of the following conditions applies to individual who connected their QuickBooks Online company to your app:
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.
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. |
There are non-UTF-8 characters in your request payload.
Use any standard library or function to set UTF-8 encoding for your request payload.
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. |
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.
To prevent this error:
Id
, SyncToken
, DisplayName
, and Active
states for all name list objects in your app’s database.Active
states.Active
state in transaction requests before sending them. Implement the appropriate logic in your app for active
= false.Error code | Message | Detail |
610 | Object Not Found | Object Not Found : Another user has deleted this transaction. |
This is usually caused by references to deleted transaction objects in requests.
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.
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. |
The Item.AssetAccountRef
isn’t set for an inventory object in your request.
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. |
A Line
element is missing from the transaction object’s request payload.
Learn more about required parameters for transaction (invoices, sales receipt, etc) API entities.
Error code | Message | Detail |
2170 | Invalid Enumeration | Invalid Enumeration : HAS_BEEN_BILLED |
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
.
Don’t manually set TimeActivity.BillableStatus
to HasBeenBilled. Let the system handle it.
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. |
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.
To prevent this error:
Id
, SyncToken
, DisplayName
, and Active
states for all name list objects in your app’s database.Active
states.Active
state in transaction requests before sending them. Implement the appropriate logic in your app for active
= false.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> |
This usually means you’re working with a stale object.
Always work with the latest version of objects. An object’s version is stored in its syncToken attribute.
Id
, type
, and syncToken
for objects in your app’s database.syncToken
in the response payload to get the latest version of an object. Use the returned syncToken
for subsequent requests.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.
Error code | Message | Detail |
6000 | A business validation error has occurred while processing your request | Business Validation Error: You must set a transaction amount. |
The TotalAmt
attribute isn’t set for the BillPayment or Payment enitities in your request. The TotalAmt
attribute is required.
Make sure the TotalAmt
attribute has a valid transaction amount in requests.
Error code | Message | Detail |
6140 | Duplicate DocNum Error | Duplicate Document Number Error : You must specify a different number. This number has already been used. |
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:
Preferences.SalesFormsPrefs.CustomTxnNumbers
attribute is set to true.Fetch and check the Preferences.SalesFormsPrefs.CustomTxnNumbers
attribute before creating any transactions.
DocNumber
with a custom pattern such as <your app name>_docnumber.DocNumber
.This prevents DocNumber
duplications when users or other apps manually enter transactions that utilize QuickBooks data.
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. |
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.
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.
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. |
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 or an item within this closed accounting period.
If a user automatically closes their books in QuickBooks Online, transactions and items 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:
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. |
The DisplayName
attribute must be unique across all customer, vendor, and employee objects.
Id
and DisplayName
attributes for all customer, vendor, and employee objects for the target QuickBooks Online company.Id
and DisplayName
attributes for name list entities (customers, vendors, employees, class, sales tax, etc) in your app’s database.DisplayName
already exists.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. |
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.
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.