Debugging common errors

The most common QuickBooks Online errors are listed here. We identified the errors along with their corresponding resolutions. 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 QuickBooks Online, the issue can stem from various sources, including configuration errors, data validation issues, or QuickBooks Online 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 QuickBooks Online 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 QuickBooks Online creation.
- Zuper App Configuration: Misconfigured settings.
- Zuper Settings: Duplicate object errors due to mismatched unique fields.
QuickBooks Online Entities :
- Primary QuickBooks Online Record: Manual modifications in QuickBooks Online conflict with sync updates.
- Associated QuickBooks Online Record: Issues fetching tax or other linked data.
- QuickBooks Online Settings: Custom transaction numbers, class tracking, or multicurrency settings.
- QuickBooks Online 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 QuickBooks Online settings.

Error Categories and Solutions

Below is a consolidated breakdown of errors, their causes, and actionable solutions, organized by category.

1. Zuper-Side Errors

• Customer not found or could not be created in QuickBooks Online

Error	Cause	Solution
Code: N/A	Invalid customer information. Examples: incorrect email format, invalid phone number.	Verify and correct the customer’s email to a valid format (e.g., user@domain.com). Fix phone number format per QuickBooks Online requirements. Retry the sync.

• Unable to upload attachment - $ in QuickBooks Online

Error	Cause	Solution
Code: N/A	Attachment exceeds QuickBooks Online’s 20MB size limit. Unsupported format (e.g., PDF).	Ensure the attachment is under 20MB. Use a supported format (e.g., JPEG, PNG). Compress or convert the file. Retry the sync.

• Unable to fetch tax from QuickBooks Online

Error	Cause	Solution
Code: N/A	Tax sync issue between Zuper and QuickBooks Online. QuickBooks Online is the tax master, and the relevant tax is not created in Zuper.	Match Zuper’s tax configuration to QuickBooks Online’s tax settings. If QuickBooks Online is the tax master, create the corresponding tax in Zuper. Update tax mapping in integration settings. Retry the sync.

• Line item not present

Error	Cause	Solution
Code: N/A	Invoice/quote has no line items. QuickBooks Online requires at least one line item.	Add at least one valid line item. Fill all required fields (e.g., description, amount). Retry the sync.

• Could not create or update product

Error	Cause	Solution
Code: N/A	Failed to get Zuper product details. QuickBooks Online doesn’t support negative price for inventory items. Bundle-level pricing not supported in QuickBooks Online / Bundle not available in QuickBooks Online. QuickBooks Online doesn’t allow creating bundles via API.	Retry the sync after some time. Set a non-negative selling price for the inventory item. Use a roll-up bundle in the invoice/estimate. Create the bundle directly in QuickBooks Online, then sync the invoice/estimate.

• Excess Payment Detected

Error	Cause	Solution
Code: N/A	Payment collected in Zuper failed to sync to QuickBooks Online. Payment then collected in QuickBooks Online; reverse sync shows payments exceed invoice total.	Usually safe to ignore as payments will match between Zuper and QuickBooks Online. Confirm payment totals align in both systems.

• Payment method not found in Zuper/QuickBooks Online

Error	Cause	Solution
Code: N/A	Payments collected in QuickBooks Online lack a payment method or use one not present in Zuper.	Add a fallback payment method in Zuper for reverse-sync from QuickBooks Online. Retry the sync.

2. QuickBooks Online API Errors

• Unsupported Operation

Error	Cause	Solution
Code: 500	QuickBooks Online plan selected in Zuper doesn’t match the subscribed QuickBooks Online plan. Technical issues (e.g., encoding or special characters).	Contact Zuper support (support@zuper.co) to verify/update the plan mapping. Ensure plan selection matches QuickBooks Online subscription. Remove or correct special characters/encoding issues. Retry the sync.

• Business Validation Error

Error	Cause	Solution
Code: 6000	QuickBooks Online business rule failed. Examples: missing GST/HST rate (Canada), agency issues, currency mismatch, missing required fields.	Read the QuickBooks Online error message for the exact cause. Update fields in Zuper (e.g., add valid GST/HST, fix currency). Retry the sync.

• Invalid Email Address Format Error

Error	Cause	Solution
Code: 2210	Customer email in Zuper is not in a valid format.	Update the email to a valid format (e.g., user@domain.com). Validate other customer details. Retry the sync.

• Invalid Reference ID Error

Error	Cause	Solution
Code: 2500	A line item name matches a master record (e.g., product category) in QuickBooks Online.	Rename the line item in Zuper to be unique (not matching any QuickBooks Online master). Retry the sync.

• Stale Object Error

Error	Cause	Solution
Code: 5010	Updating an outdated object version. Concurrent edits in QuickBooks Online by the OAuth user.	Contact Zuper support to refresh the integration connection. Avoid concurrent edits on the same record in QuickBooks Online. Retry the sync.

• Object not found

Error	Cause	Solution
Code: N/A	Referenced record (e.g., customer/product) is deleted or inactive in QuickBooks Online.	Check QuickBooks Online for the referenced record’s status. Reactivate or recreate the record. Retry the sync.

• Incorrect account type or missing account reference

Error	Cause	Solution
Code: N/A	Referenced account is invalid or missing in QuickBooks Online.	Verify the account exists and has the correct type (e.g., income, expense). Update account mapping in Zuper integration settings. Retry the sync.

3. Duplicate Errors

• Duplicate Object Error

Error	Cause	Solution
Code: 630	Object in Zuper violates a unique constraint in QuickBooks Online (e.g., reference ID, name).	Update the object in Zuper to ensure uniqueness (e.g., change reference ID or name). Check QuickBooks Online for conflicting records. Retry the sync.

• Duplicate Document Error / Duplicate Document Number Error

Error	Cause	Solution
Code: 6140	Document number in Zuper already exists in QuickBooks Online. Often occurs when existing QuickBooks Online records predate integration and Zuper uses a similar series with ID preference set to Zuper.	Use a unique document number in Zuper or enable auto-numbering in QuickBooks Online. Set ID preference to “QuickBooks Online” and retry. Note: Document numbers will not match between Zuper and QuickBooks Online.

• Duplicate Name Exists Error

Error	Cause	Solution
Code: 6240	Customer name exists in QuickBooks Online but with a different QuickBooks Online ID. Often due to manual deletion and recreation in QuickBooks Online.	Change the customer’s display name in Zuper to be unique. Or merge or rename duplicates in QuickBooks Online to align with Zuper. Retry the sync.

4. Other Errors

• Unable to Fetch Customer from QuickBooks Online

Error	Cause	Solution
Code: N/A	Unknown issues blocking customer retrieval. Possible connectivity or permission problems.	Verify OAuth connection and API permissions. Confirm the customer exists and is active in QuickBooks Online. Re-authenticate the integration if needed. Retry the sync.

• Unable to Fetch the Estimate from QuickBooks Online

Error	Cause	Solution
Code: N/A	Unknown issues fetching the estimate. Possible data mismatches or QuickBooks Online access issues.	Check the estimate’s status in QuickBooks Online and sync requirements. Re-authenticate integration and confirm connectivity. Retry the sync.

• All Other Error Codes

Error	Cause	Solution
Code: N/A	Unlisted or unknown issues (connectivity, permissions, data problems).	Contact Zuper support (support@zuper.co) with the specific error code and sync history details. Provide logs or screenshots to assist troubleshooting.

• Customer not present in QuickBooks Online for the given ID: XXXX

Error	Cause	Solution
Code: N/A	Customer synced from Zuper to QuickBooks Online but was made inactive. Sometimes due to temporary connection issues preventing retrieval.	Reactivate the customer in QuickBooks Online. Retry the sync. If connection-related, try again after some time.

Best Practices to Prevent Sync Errors

Verify Integration Setup:
- Ensure OAuth is completed correctly and the API key is valid.
- Confirm that the QuickBooks Online 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 QuickBooks Online that could conflict with sync updates.
QuickBooks Online Configuration:
- Enable or disable features like custom transaction numbers, class tracking, or multicurrency as needed.
- Ensure tax settings in QuickBooks Online align with Zuper’s configuration.
Monitor Sync Activity:
- Regularly review sync history and activity logs to identify and address issues early.
- Compare QuickBooks Online’s transaction audit history with Zuper’s invoice activity for discrepancies.
User Coordination:
- Prevent the OAuth user from editing QuickBooks Online 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 QuickBooks Online API error codes and Zuper’s error documentation for detailed troubleshooting.
Support: If issues persist, contact Zuper or QuickBooks Online support with specific error details from the sync history.

Diagnostic Tools

Sync Activity: Review to identify created or associated records during sync.
QuickBooks Online 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 QuickBooks Online’s API documentation and Zuper’s error code reference.

​Overview of Sync Issues

​Sources of Errors

​Error Categories and Solutions

​1. Zuper-Side Errors

​• Customer not found or could not be created in QuickBooks Online

​• Unable to upload attachment - $ in QuickBooks Online

​• Unable to fetch tax from QuickBooks Online

​• Line item not present

​• Could not create or update product

​• Excess Payment Detected

​• Payment method not found in Zuper/QuickBooks Online

​2. QuickBooks Online API Errors

​• Unsupported Operation

​• Business Validation Error

​• Invalid Email Address Format Error

​• Invalid Reference ID Error

​• Stale Object Error

​• Object not found

​• Incorrect account type or missing account reference

​3. Duplicate Errors

​• Duplicate Object Error

​• Duplicate Document Error / Duplicate Document Number Error

​• Duplicate Name Exists Error

​4. Other Errors

​• Unable to Fetch Customer from QuickBooks Online

​• Unable to Fetch the Estimate from QuickBooks Online

​• All Other Error Codes

​• Customer not present in QuickBooks Online for the given ID: XXXX

​Best Practices to Prevent Sync Errors

​Additional Notes

​Diagnostic Tools