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"
}

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

• They aren’t an admin user
• Their admin status changed
• Their user profile was completely removed from the QuickBooks Online company.

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.

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:

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:

• When your app first connects to a user’s QuickBooks Online company, cache the Id, SyncToken, DisplayName, and Active states for all name list objects in your app’s database.
• Use webhooks or the change data capture operation to track changes to name list objects’ Active states.
• Always keep your app’s internal database up-to-date.
• Validate the referenced object’s Active state in transaction requests before sending them. Implement the appropriate logic in your app for active = false.

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:

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.

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.

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.

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:

• When your app first connects to a user’s QuickBooks Online company, cache the Id, SyncToken, DisplayName, and Active states for all name list objects in your app’s database.
• Use webhooks or the change data capture operation to track changes to name list objects’ Active states.
• Always keep your app’s internal database up-to-date.
• Validate the referenced object’s Active state in transaction requests before sending them. Implement the appropriate logic in your app for active = false.

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.

• When your app first connects to a user’s QuickBooks Online company, cache the Id, type, and syncToken for objects in your app’s database.
• Use webhooks or the change data capture operation to track changes to objects.
• Before performing any update or delete operation, retrieve the latest version of the object.
• Use the syncToken in the response payload to get the latest version of an object. Use the returned syncToken for subsequent requests.
• Always keep your app’s internal database up-to-date.

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.

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.

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:

• The Preferences.SalesFormsPrefs.CustomTxnNumbers attribute is set to true.
• QuickBooks users enable the “Warn if duplicate check/bill number is used” message via the QuickBooks Online UI. Users can accept the warning and allow duplicate doc numbers. It’s not possible to test if this setting is enabled, or accept warnings programmatically, via the QuickBooks Online Accounting API.

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

• If it’s true, create the DocNumber with a custom pattern such as <your app name>_docnumber.
• If it’s false, QuickBooks will automatically assign the DocNumber.

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

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.

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:

• Add logic to your app to query the QuickBooks Online company’s admin user for the account period close date when they first connect to your app.
• Use the account period close date to determine if a target transaction is within the closed accounting period before sending your request.

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

• Fetch the Id and DisplayName attributes for all customer, vendor, and employee objects for the target QuickBooks Online company.
• Persist the Id and DisplayName attributes for name list entities (customers, vendors, employees, class, sales tax, etc) in your app’s database.
• Before creating new customer, vendor, or employee objects, check the database to determine if the DisplayName already exists.
• Use webhooks or the change data capture operation to track changes to objects.
• Always keep your app’s internal database up-to-date.
• For cases where multiple objects use the same name, create a naming scheme to distinguish them. For example, “John Smith” may be a customer and vendor. Store his name in the customer object as “John Smith (customer)” and in the vendor object as “John Smith (vendor)”.

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.