Handling common errors

Here are the most common errors generated by the QuickBooks Online API, based on occurrence from our server logs. The section for each message includes common causes and preventive tips to help you proactively mitigate against these common errors in your app.

Errors included in this page are listed below according to the Fault.Error.Message text from the error response payload:

CodeMessage
120Authorization Failure
500Unsupported Operation
610Object Not Found (for transaction objects)
Object Not Found (for name list objects)
2020Required Param Missing (for Line elements)
Required Param Missing (for inventory items)
2170 Invalid Enumeration
2500Invalid Reference Id
5010 Stale Object Error
6000A business validation error has occurred while processing your request
6190Invalid Company Status
6140Duplicate Doc Num
6210Account Period Closed
6240Duplicate Name Exists Error
6540Deposited Transaction cannot be changed

Error response payload

Columns in the tables correspond to fields in the error return response payload:

{
    "Fault":
    {
        "Error": [
        {
            "Message": "<message>",
            "Detail": "<detail>",
            "code": "<code>",
            "element": ""
        }],
        "type": "ValidationFault"
    },
    "time": "2017-09-29T09:17:31.892-07:00"
}

120 Authorization Failure

CodeMessageDetail
120Authorization Failure: --11014-You do not have access to use QuickBooks Online Plus.

Common cause

The user admin who connected his or her QuickBooks Online company with your app is either not an admin anymore or has been removed from the QuickBooks Online company.

Remedy

  • Reach out to the former QuickBooks Online company owner to check whether the company still needs your app, or whether to revoke access.
  • Consider the connection to this QuickBooks Online company disconnected.

500 Unsupported Operation

CodeMessageDetail
500Unsupported OperationOperation 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 some non-UTF-8 characters present in the API request payload.

Remedy

  • Use any standard library or functions to set UTF-8 encoding to your API request payload.

610 Object Not Found

CodeMessageDetail
610Object Not FoundObject Not Found :Something you' re trying to use has been made inactive. Check the fields with accounts

Common cause

A reference to an inactive name list object (like Customer, Vendor, Account, and so on) is made from a transaction. For example, the customer object referenced in an Invoice payload with the Invoice.CustomerRef element is inactive; that is, Customer.Active is set to false in the customer object. This error message is similar to the below 610 Object Not Found for transaction objects.

Remedy

Follow these steps to prevent this error.

  1. When the app first connects to a QuickBooks Online company, cache the Id, SyncToken, DisplayName, and Active state of all the name list objects in your application' s database.
  2. Leverage the Webhooks or Change Data Capture APIs to monitor changes of the name list object's Active states. Keep you app's internal database up-to-date.
  3. Validate the Active state of the referenced object in the transaction request payload before sending. Implement the appropriate logic in your app for Active=false.

610 Object Not Found

CodeMessageDetail
610Object Not FoundObject Not Found :Another user has deleted this transaction.

Common cause

This error message, similar to the above 610 Object Not Found for name list objects, applies to transaction objects.The target transaction object in a QuickBooks Online API request has been deleted.

Remedy

  • Deleted transactions are removed from the QuickBooks company. For this reason, leverage the WebHooks and Change Data Capture resources to keep track of deleted and added transactions.

    2020 Required Param Missing

    CodeMessageDetail
    2020Required Param MissingRequired parameter An inventory asset account is required if you are tracking inventory quantities for this product. is missing in the request

    Common cause

    The Item.AssetAccountRef is not set in the Item object's request payload.

    Remedy

    • You must include the Item.AssetAccountRefwhen creating an inventory item. Consult information for the Item resource here.

    2020 Required Param Missing

    CodeMessageDetail
    2020Required Param MissingRequired parameter Line is missing in the request.

    Common cause

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

    Remedy

    2170 Invalid Enumeration

    CodeMessageDetail
    2170Invalid EnumerationInvalid Enumeration : HAS_BEEN_BILLED

    Common cause

    The app cannot directly set TimeActivity.BillableStatus to HasBeenBilled. The TimeActivities object's billable status is set by the system to HasBeenBilled once an Invoice object links to it via Invoice.LinkedTxn

    Remedy

    • Do not attempt to set TimeActivity.BillableStatus to HasBeenBilled.

    2500 Invalid Reference Id

    CodeMessageDetail
    2500Invalid Reference IdInvalid Reference Id : Something you' re trying to use has been made inactive. Check the fields with accounts>

    Common cause

    A request is made to an inactive name list object (such as a Customer, Vendor, or Account).The Active attribute in the target name list object is set to false in the object. This error message is similar to the above 610 Object Not Found for references to a name list object from a transaction.

    Remedy

    Follow these steps to prevent this error.

    1. When the app first connects to a QuickBooks Online company, cache the Id, SyncToken, DisplayName, and Active state of all the name list objects in your application' s database.
    2. Leverage the WebHooks and Change Data Capture resources to monitor changes of the name list object's Active states. Keep your app's internal database up-to-date.
    3. Validate the Active state of the target object's request payload before sending. Implement the appropriate logic in your app for Active=false.

    5010 Stale Object Error

    CodeMessageDetail
    5010Stale Object ErrorStale 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

    You are not working with the latest version of the object. The object's version is stored in its SyncToken attribute. 

    Remedy

    • (Preferred) Store the Id, type, and SyncToken in your application's database for objects your app plans to use. Using CDC or Webhooks resources, monitor object changes. Then, just for changed objects, retrieve the latest version and use the SyncToken from its response payload. 
    • Before performing any update or delete operation, retrieve the latest version of the object. Use the SyncTokenreturned in that response payload in the subsequent request payload. This technique is inefficient because it requires a read operation for each update.
    • Read about sync tokens here.

    6000 A business validation error has occurred while processing your request

    CodeMessageDetail
    6000A business validation error has occurred while processing your requestBusiness Validation Error: You must set a transaction amount.

    Common cause

    The TotalAmt attribute is is not set in the request payload for BillPayment or Payment objects. This attribute is required.

    Remedy

    • Make sure that TotalAmt is set with a valid transaction amount in BillPayment and  Payment object request payloads.

    6140 Duplicate Doc Num Error

    CodeMessageDetail
    6210Duplicate DocNum ErrorDuplicate Document Number Error : You must specify a different number. This number has already been used.

    Common cause

    At transaction create time, the app sends a string in DocNumber that happens to duplicate one in an existing transaction object when both of these conditions exist:

    • Preferences.SalesFormsPrefs.CustomTxnNumbers is set to true.
    • Warn if duplicate check/bill number is used is set to true via the QuickBooks Online UI. A UI user can accept the warning to allow the duplicate doc number. Unfortunately, this setting cannot be tested nor can the warning be accepted programmatically via the QuickBooks Online API.

    Remedy

    • Fetch and check the Preferences.SalesFormsPrefs.CustomTxnNumberssetting before creating any transactions. If set to true, create the DocNumber with a custom pattern such as <your app name>_docnumber. This prevents DocNumber collisions when transactions are manually entered by the user or by a different app.

    6190 Invalid Company Status

    CodeMessageDetail
    6190Invalid Company StatusSubscription 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 subscription state for the target QuickBooks Online company is invalid for the given operation. For example, the app attempts a write operation to a company with a read-only status.

    Remedy

    • Check the company subscription state via the SubscriptionStatus name/value pair in the CompanyInfo object.
    • Design your app to take action based on the subscription state. This may include reaching out to the QuickBooks Online company owner to decide on further steps such as disconnecting the connection or waiting for the subscription to be valid.

    6210 Account Period Closed

    CodeMessageDetail
    6210Account Period ClosedThe 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

    An attempt is made to modify a transaction within a closed accounting period for the company.

    Remedy

    QuickBooks Online can be configured to automatically close the books at the end of the fiscal year, after which transactions that fall within the closed year cannot be modified. There is no way to determine the fiscal year end or if the books are closed via the QuickBooks Online API.

    • Add logic to the app to query the admin user for the account period close date at the time the connection is made to the QuickBooks company.
    • Using the account period close date, determine if the target transaction in the request is within the closed accounting period before sending it. Take appropriate action.

    6240 Duplicate Name Exists 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.  

    Remedy

    • Fetch the Id and DisplayNameattributes for all Customer, Vendor, and Employee objects from the target QuickBooks Online company and persist them in your application' s database.
    • Before creating a new Customer, Vendor, or Employee object, check the database to determine if the DisplayName already exists. Keep your app's database up to date via the Change Data Capture and Webhooks resources.
    • In cases where the same name occurs in multiple objects, create a 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).

    6540 Deposited Transaction cannot be changed

    CodeMessageDetail
    6540Deposited Transaction cannot be changedThis 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 element. 

    A customer payment is recorded using either the Payment (against an Invoice) or SalesReceipt (for a direct purchase) resources.  The payment captures the money into the UndepositedFunds account. A subsequent Deposit object moves the money from UndepositedFunds to the desired bank account and links back to the original Payment or SalesReceipt object.

    Remedy

    A transaction (Payment or SalesReceipt) that is already deposited and linked with a deposit entry cannot be modified. 


    Did you find this page helpful?
    Your feedback helps us make our docs better. Please let us know if this page helped you, or if it needs improvement.

     Got Questions? Get Answers in our developer forums.