QuickBooks Online
Debugging common errors
The most common QuickBooks Online errors are listed here. We came up with the errors along with the resolution for each. If you do not find any errors listed, kindly reach out to support@zuper.co
Overview of Sync Issues
When data fails to sync between Zuper and QBO, the issue can stem from various sources, including configuration errors, data validation issues, or QBO API limitations. The absence of an error in sync history often indicates that the record was created or updated by the same user whose API key was used for the integration. Other scenarios include incorrect installation (e.g., incomplete OAuth) or specific errors logged in the sync history, which can be either Zuper-validated or QBO API errors.Sources of Errors
- Zuper Entities:
- Primary Zuper Record: Missing line items or invoices not in a sync-ready status.
- Associated Zuper Object: Incorrect customer details for QBO creation.
- Zuper App Configuration: Misconfigured settings.
- Zuper Settings: Duplicate object errors due to mismatched unique fields.
- QBO Entities:
- Primary QBO Record: Manual modifications in QBO conflicting with sync updates.
- Associated QBO Record: Issues fetching tax or other linked data.
- QBO Settings: Custom transaction numbers, class tracking, or multicurrency settings.
- QBO Plan: Limitations, such as a lack of class tracking support.
- Combined Issues: Errors may arise from a combination of configuration and missing data or unsupported QBO settings.
Diagnostic Tools
- Sync Activity: Review to identify created or associated records during sync.
- QBO Transaction Audit History: Compare with Zuper’s invoice activity to distinguish user-initiated changes from integration-driven changes.
Error Categories and Solutions
Below is a consolidated breakdown of errors, their causes, and actionable solutions, organized by category. The tables have been verified and merged to avoid duplication while incorporating all relevant details.1. Zuper-Side Errors
These errors originate from Zuper’s validation or backend processes, often related to data issues or configuration.| Error | Error Code | Cause | Solution |
|---|---|---|---|
| Customer not found or could not be created in QBO | Invalid customer information (e.g., incorrect email format, invalid phone number). | Verify and correct the customer’s email address (e.g., user@domain.com) and phone number format in Zuper to meet QBO’s requirements. After updating, retry the sync. | |
| Unable to upload attachment - $ in QBO | Attachment exceeds QBO’s 20MB size limit or is in an unsupported format (e.g., PDF). | Ensure the attachment is under 20MB and in a supported format (e.g., JPEG, PNG). Compress or convert the file if needed, then retry the sync. | |
| Unable to fetch tax from QBO | There is a tax sync issue, often when QBO is the tax master and the relevant tax is not created in Zuper. | Verify that Zuper’s tax configuration matches QBO’s tax settings. If QBO is the tax master, create the corresponding tax in Zuper or update the tax mapping in the integration settings, then retry. | |
| Line item not present | The invoice or quote lacks at least one line item required for syncing. | Add at least one valid line item to the invoice or quote in Zuper, ensuring all required fields (e.g., description, and amount) are populated. Then, retry the sync. |
2. QBO API Errors
These errors are returned by the QBO API, often due to validation failures or configuration mismatches.| Error | Error Code | Cause | Solution |
|---|---|---|---|
| Unsupported Operation | 500 | The QBO plan selected in Zuper’s configuration does not match the user’s subscribed QBO plan, or technical issues (e.g., encoding problems). | Contact Zuper support at support@zuper.co to verify and update the QBO plan in the integration settings. Ensure the selected plan aligns with the user’s QBO subscription. Check for encoding issues (e.g., special characters) in the data, correct them, and retry the sync. |
| Business Validation Error | 6000 | A business validation rule fails in QBO, such as missing GST/HST rates (e.g., in Canada), agency issues, currency mismatches, or missing required fields. | Review the error message to identify the cause (e.g., missing tax rate, incorrect currency). Update the relevant field in Zuper (e.g., add a valid GST/HST rate or correct the currency) and retry the sync. |
| Invalid Email Address Format Error | 2210 | The customer email specified in Zuper is in an incorrect format (e.g., missing @ or invalid domain). | Modify the email address in Zuper to a valid format (e.g., user@domain.com). Verify other customer details, then retry the sync. |
| Invalid Reference ID Error | 2500 | A line item in a transaction has the same name as a master record (e.g., a product category) in QBO. | Modify the line item name in Zuper to be unique and distinct from any master record names in QBO. Retry the sync. |
| Stale Object Error | 5010 | The object being updated is not the latest version, often due to simultaneous edits in QBO by the OAuth user. | Contact Zuper support at support@zuper.co to refresh the integration connection and ensure the latest object version is synced. Coordinate with the QBO user to avoid concurrent edits, then retry. |
| Object not found | The referenced record (e.g., customer or product) in QBO is deleted or inactive. | Check QBO to ensure the referenced customer or product is active. Reactivate or recreate the record if necessary, then retry the sync. | |
| Incorrect account type or missing account reference | The account referenced in the transaction is invalid or missing in QBO. | Verify that the account referenced in the transaction exists in QBO and is of the correct type (e.g., income, expense). Update the account mapping in Zuper’s integration settings and retry the sync. |
3. Duplicate Errors
These errors occur when unique constraints in QBO are violated due to duplicate data.| Error | Error Code | Cause | Solution |
|---|---|---|---|
| Duplicate Object Error | 630 | An object in Zuper (e.g., customer, product) has properties (e.g., reference IDs) that violate QBO’s unique constraint. | Modify the object’s properties in Zuper to ensure uniqueness (e.g., update the reference ID or name). Verify no conflicting records exist in QBO, then retry the sync. |
| Duplicate Document Error | 6140 | The invoice number specified in Zuper is already in use in QBO. | Specify a unique invoice number in Zuper or enable automatic numbering in QBO settings to avoid conflicts. Retry the sync. |
| Duplicate Name Exists Error | 6240 | A customer name in Zuper already exists in QBO with a different QBO ID, often due to manual deletion and recreation in QBO. | Modify the customer’s display name in Zuper to be unique or merge/rename the duplicate customer in QBO to align with the Zuper record. Retry the sync. |
4. Other Errors
These are fallback or unlisted errors not covered by the above categories.| Error | Error Code | Cause | Solution |
|---|---|---|---|
| Unable to Fetch Customer from QBO | Unknown issues are preventing customer data retrieval, possibly due to connectivity or permissions. | Verify the OAuth connection and API key permissions. Ensure the customer exists and is active in QBO. If necessary, re-authenticate the integration and retry. | |
| Unable to Fetch the Estimate from QBO | Unknown issues with estimate retrieval, often due to data mismatches or QBO access issues. | Check the estimate status in QBO and ensure it matches Zuper’s sync requirements. Re-authenticate the integration, confirm connectivity, and retry the sync. | |
| All Other Error Codes | Unknown or unlisted issues not covered by the above error codes, potentially related to connectivity, permissions, or data issues. | Contact Zuper support at support@zuper.co with the specific error code and details from the sync history. Provide relevant logs or screenshots to assist in troubleshooting. |
Best Practices to Prevent Sync Errors
- Verify Integration Setup:
- Ensure OAuth is completed correctly and the API key is valid.
- Confirm that the QBO plan selected in the app configuration matches the user’s subscription.
- Data Validation:
- Regularly check customer details, tax settings, and line items in Zuper for accuracy.
- Avoid manual changes in QBO that could conflict with sync updates.
- QBO Configuration:
- Enable or disable features like custom transaction numbers, class tracking, or multicurrency as needed.
- Ensure tax settings in QBO align with Zuper’s configuration.
- Monitor Sync Activity:
- Regularly review sync history and activity logs to identify and address issues early.
- Compare QBO’s transaction audit history with Zuper’s invoice activity for discrepancies.
- User Coordination:
- Prevent the OAuth user from editing QBO records during sync to avoid stale object errors.
- Unique Identifiers:
- Ensure customer names, invoice numbers, and reference IDs are unique to avoid Duplicate Object (630), Duplicate Document (6140), and Duplicate Name Exists (6240) errors.
- Use distinct names for line items to prevent Invalid Reference ID Errors (Error Code: 2500).
Additional Notes
- Multiple Causes: Sync failures may result from combined issues (e.g., missing data and incorrect settings). Address each potential cause systematically.
- Documentation: Refer to the QBO API error codes and Zuper’s error documentation for detailed troubleshooting.
- Support: If issues persist, contact Zuper or QBO support with specific error details from the sync history.
Diagnostic Tools
- Sync Activity: Review to identify created or associated records during sync.
- QBO Transaction Audit History: Compare with Zuper’s invoice activity to distinguish user-initiated changes from integration-driven changes.
- Error Codes: Use the provided error codes to pinpoint the issue and apply the corresponding solution.
- Combined Issues: Some errors may result from multiple causes (e.g., incorrect plan selection and missing data). Address each issue systematically using the provided solutions.
- Escalation: For errors requiring Zuper support (e.g., Unsupported Operation, Stale Object, or unlisted error codes), provide detailed information, including the error code, sync history logs, and affected records.
- Documentation: For further details on specific error messages, refer to QBO’s API documentation and Zuper’s error code reference.