Knowledgebase: Others
[QODBC-Online] Troubleshooting - Top QuickBooks Online API Errors and How to Handle Them
Posted by Jack - QODBC Support on 13 June 2017 01:49 PM

Troubleshooting - Top QuickBooks Online API Errors and How to Handle Them

How to Handle Frequently Returned QuickBooks Online API Error Messages

In this article, we’ll go through a list of these error responses and provide some recommendations and best practices for handling them. Reducing errors helps reduce failed customer interactions.

Frequently Returned Errors

NoError-CodeError-MessageError-Detail
1. 6240 Duplicate Name Exists Error The name supplied already exists: Another customer is already using this name. Please use a different name.
2. 6210 Duplicate Document Number Error Duplicate Document Number Error: You must specify a different number. This number has already been used.
3 610 Object Not Found Object Not Found: Something you’re trying to use has been made inactive. Check the fields with accounts.
4 120 Authorization Failure AuthorizationFailure: –11014-You do not have access to use QuickBooks Online Plus.
5 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 610 Object Not Found Object Not Found: Another user has deleted this transaction.
7 2500 Invalid Reference Id Invalid Reference Id: Something you’re trying to use has been made inactive. Check the fields with accounts.
8 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 removes it.
9 2170 Invalid Enumeration Invalid Enumeration: HAS_BEEN_BILLED
10 6000 A business validation error has occurred while processing your request Business Validation Error: You must set a transaction amount.
11 6210 Account Period Closed The accounting 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 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 2020 Required param missing Required parameter: Line is missing in the request.
14 2020 Required param missing Required parameter: An inventory asset account is required if you are tracking inventory quantities for this product.
15 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

Error CodeError MessageError Detail
6240 Duplicate Name Exists Error The name supplied already exists.

Description – The name you are trying to insert has already existed in customer/vendor/employee table. Before creating any new customer, vendor or employee, you 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.

ERROR NO – 2

Error CodeError MessageError Detail
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' or 'RefNumber', which acts as a transaction reference.

By default, QuickBooks Online generates a unique DocNumber/RefNumber 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' or 'RefNumber'. End users can also enable the ‘Warn if duplicate check/bill number is used’ feature which warns a UI user when a duplicate 'DocNumber' or 'RefNumber' 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' or 'RefNumber'

ERROR NO – 3

Error CodeError MessageError Detail
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. You can get InActive object details by using below sample query.

For Example, If you want to get Customer status who is InActive, then you can use below sample query:
Select Name, IsActive from Customer where IsActive = false and Name = 'John'

ERROR NO – 4

Error CodeError MessageError Detail
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 NO – 5

Error CodeError MessageError Detail
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 NO – 6

Error CodeError MessageError Detail
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 NO – 7

Error CodeError MessageError Detail
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 NO – 8

Error CodeError MessageError Detail
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 removes 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.

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

Error CodeError MessageError Detail
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 NO – 10

Error CodeError MessageError Detail
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/TotalAmount, which should always have a valid transaction amount.

When creating any BillPayment or Payment entry, make sure that TotalAmt/TotalAmount is set to a valid transaction amount.

 

ERROR NO – 11

Error CodeError MessageError Detail
6210 Account Period Closed The accounting 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 NO – 12

Error CodeError MessageError Detail
500 Unsupported Operation Operation com.sun.org.apache.xerces.internal.impl.io.MalformedByteSequenceException: Invalid byte 1 of the 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 NO – 13

Error CodeError MessageError Detail
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 NO – 14

Error CodeError MessageError Detail
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.

The application should pass an Inventory Asset Account reference while creating Inventory Item objects using the API.

 

ERROR NO – 15

Error CodeError MessageError 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.

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

Source - https://developer.intuit.com/hub/blog/2017/06/08/top-quickbooks-online-api-errors-and-how-to-handle-them.

(0 vote(s))
Helpful
Not helpful

Comments (0)
Post a new comment
 
 
Full Name:
Email:
Comments:
CAPTCHA Verification 
 
Please complete the captcha below (we use this to prevent automated submissions).