Troubleshooting and FAQs

Common errors that you may encounter and frequently asked questions

Status codes

Code	Reason
1000	In Progress
1010	In Progress (Long running - over ten minutes)
2000	Success (Data written)
2040	Success (No data written)
4000	Configuration Error
4040	Company deleted/de-authorized
4220	Company deleted/de-authorized
4260	Accounting software billing expiry
5000	Generic Server error
5080	Duplication protection
5120	Data processing error
5130	Data write error

Error messages

This section describes the errors that are related to Sync for Commerce configuration. Some of them can be avoided by following this set of best practices:

• Ensure that the Codat company that you create for your merchant has both accounting and commerce data connections and they are linked correctly.
• If you are re-linking the company, make sure that the previous one is deleted.
• Ensure that the invoice status for Payments is set to submitted.
• Avoid using payout/prepaid accounts for Payments.
• Make sure to configure the grouping for all the features.
• When choosing configuration options, only use the options provided by Codat.

How to resolve configuration errors

Error message	Error resolution
Company needs to have two valid data connections.	This error surfaces if a company does not have 2 valid data connections OR both data connections do not have the linked status. Ensure that the Codat company created for the merchant has 2 valid data connections. One commerce and one accounting connection are required. Ensure that the Codat company has both data connection statuses set to linked by using the public API connection resource OR via the-no code merchant link journey using the link URL generated by the Codat app portal.
To sync fees: - Payments section needs to exist - Payments account id needs to be set	The Fees feature cannot be used until the Payment feature is configured. The merchant should complete the configuration of Payments in order to sync Fees.
Payments config invalid. {prepaid account} should not match {prepaid payment account}. Accounts config invalid. Prepaid account in Sales should not match {CommerceAccountType. PrepaidPayment} in Payments."	The prepaid account and the payment account should not be the same. Reconfigure the selected accounts for prepaid and prepaid payments.
Payments config invalid. {Card Acount} should not match {Payout Account}.	This error surfaces if the account selected for Payments matches the payout account. Reconfigure the selected accounts for payments and payouts.
No sales customer has been configured.	This error surfaces if the sales customer is missing from the configuration. Configure the sales customer from the available options on the config options.
Selected customer not present in customer options.	This error surfaces if the configured sales customer does not match a valid customerId present in the customerOptions. Note: The customerOptions are customer records fetched from the merchant's accounting software. During the onfiguration, select from the available options under the customerOptions on the Codat configuration API. selectedCustomerId must always match with a record surfaced in the customerOptions objects.
Selected Account is not a valid option.	The selectedAccountId value for the nominal account for paymentFees configuration is not from the list of nominal accounts surfaced under accountOptions or is an invalid value. During the configuration, only select from the available options under accountOptions on the Codat configuration API. selectedAccountId must always match a valid record surfaced in the accountOptions objects.
No grouping period selected. Grouping period selected not from options.	Merchants should be able to configure grouping for their invoices. In Sync for Commerce, grouping is done by time (daily) and by country/location of orders. Note: At the time of writing, the only time-based grouping option available is daily. This means all orders of a day would be grouped into a daily invoice. During the configuration, the grouping object in the config API has groupingPeriod.selectedGroupingPeriod must have a value available from the groupingPeriodOptions. If in the grouping object in the config API the groupingPeriod.selectedGroupingPeriod is set to null, an error surfaces stating there's no grouping period selected. If the grouping object is set to any value that is not from the groupingPeriodOptions, then an error is thrown stating that the value was not selected from the available options. Update the configuration on the Codat configuration API with a valid grouping period option.
Invalid invoice level grouping selected.	Merchants should be able to configure grouping for their invoices. In Sync for Commerce, grouping is done by time (daily) and by country/location of orders. This error surfaces for the locations-based grouping where selectedGroupByOptions value is not from groupByOptions. During the configuration, the grouping object in the config API has groupingLevels.invoiceLevels. selectedGroupByOptions must have a value available from the groupByOptions. Update the configuration on the Codat configuration API with a valid invoice-level grouping option.
Invalid invoice line level grouping selected.	This error surfaces for invalid groupings on grouping.invoiceLineLevel based grouping where selectedGroupByOptions value is not from groupByOptions. During the configuration, the grouping object in the config API that has groupingLevels.invoiceLineLevel. selectedGroupByOptions must have a value available from groupByOptions. Update the configuration on the Codat configuration API with a valid line-level grouping option.
Payments cannot be enabled if invoice status is set to draft.	Payments cannot be enabled for synchronization if the invoices are not Active and are set to the Draft status. A draft invoice cannot have any associated payments. The merchant should change the preferred invoice status for Payments to Submitted.
Config contains required accounts without selections.	Configuration requires accounts to be selected. This error surfaces if any of the required accounts is not selected (e.g., Sales). SMB has not selected a required nominal account for writing sales/commerce data against. Make sure that the merchant cannot complete the configuration without selecting the accounts for required features.
No Sales Account Present.	This error surfaces if the merchant's accounting software has no nominal account categorized as a Sales account. You can build a feature to create a nominal account in the merchant’s accounting software, leveraging Codat’s Sync or public Core API resources. The merchants can manually add a Sales account on their respective accounting software.
No schedule selected frequency.	This error surfaces if no schedule was configured during the configuration stage. Configure the data synchronization schedule.
Selected schedule frequency not present in options.	This error surfaces if the configured schedule does not conform to the set of options surfaced by the configuration API. Configure a valid syncing schedule from the available scheduler options.
No selected invoice status.	This error surfaces if invoice status is was not selected. During the configuration, select the preferred invoice status (Submitted or Draft). Note: Payments cannot be synchronized if their Invoice status is set to Draft.
Invalid invoice status selected (must be submitted or draft).	The invoice status to be selected must be Submitted or Draft. Any other value will lead to this error being surfaced. During the configuration, select the preferred invoice status (Submitted or Draft).
Tax rate is missing selected tax rate id.	This exception surfaces if the tax rate was not set during the configuration. Reconfigure the tax rate on the Codat configuration API using the provided options.
Selected tax rate id for {key}% tax-rate has no options.	This errors surfaces if the selected tax rate is not available or is not from the list of supported tax rates. Reconfigure the tax rate on the Codat configuration API using the provided options. During the configuration, only use the options available on the config API.
No fees supplier has been configured. Selected supplier not present in supplier options.	These error surfaces if no fees supplier has been provided or it does not match any of the options provided by Codat. During the configuration, select the fees provider from the options available on the config API.

Post-configuration errors

After the commerce data is delivered into the merchant's accounting software, there are still some things to keep in mind to ensure that Sync for Commerce performs well:

• Advise your merchants to not update, deactivate or delete the accounts they selected to use with Sync for Commerce.
• Advise your merchants not to change the settings on the selected accounts (for example, tax rates) as this will result in a synchronization error.

How to resolve post-configuration errors

Error message	Error description and resolution
The following account(s) were not found (Payment account - Account Id): {Account - Id}. Please configure your Sync settings to update these accounts.	During the scheduled data sync, validation verifies that the data in the selected nominal accounts is consistent and no accounts have been changed or deleted. This error surfaces in case any such accounts are detected. To resolve, reconfigure selected accounts on the Codat configuration API.
Account Id is not in an Active state.	During the first stage of the sync, validation checks to verify that the data in the selected nominal accounts is consistent and no accounts have status other than Active. This error is surfaced in case any such accounts are detected. To resolve, reconfigure the selected accounts on the Codat configuration API. Ensure that nominal accounts are not set to any other status than active, i.e. archived or deleted.
Customer is not in an Active state.	During the first stage of the sync, validation checks to verify that no salesCustomer data from the merchant’s accounting software in customerOptions is set to any other status other than Active. This error is surfaced in case any such customers are detected. To resolve, reconfigure salesCustomer on the configuration API endpoint. Ensure that selectedCustomerId is not any in other status other than Active.
Customer {customerId} does not exist.	During the first stage of the sync, validation checks to verify that salesCustomer is consistent and no customer data has been changed or deleted. This error is surfaced in case any such changes are detected. To resolve, reconfigure selected accounts on the Codat configuration API.
Supplier does not exist.	During the first stage of the sync, validation checks to verify that supplier data is consistent and no customer data has changed or been deleted. This error is surfaced in case any such changes are detected. To resolve, reconfigure supplier on the Codat configuration API.
Supplier is not in an Active state.	During the first stage of the sync, validation checks to verify that no supplier data is set to any other state except for Active. This error is surfaced in case any inactive suppliers are detected. To resolve, reconfigure the supplier on the config API.
Tax Rate {taxRateId} does not exist. The following Tax Rates are invalid: {Tax rate}.	During the first stage of the sync, validation checks to verify that the tax rate data is consistent and no tax rate data has been changed or deleted. This error is surfaced in case any updated tax data is detected. To resolve, reconfigure the tax rate on the config API.

Errors resolved by Codat

To resolve these errors, contact your Codat representative.

Error message	Error description and resolution
No company was found with ID.	This exception is thrown when a company record does not exist. It may have previously existed and been deleted.
Date overlaps with a previous sync date range.	This error surfaces when a scheduled daily sync overlaps or conflicts with a manually triggered sync.

FAQs

How does Codat avoid creating duplicates in the accounting software?

During a sync, we check the createdDate of individual records (orders, payments, and transactions). We compare this date with the start and end dates and times of the sync period. If the record's createdDate is within the sync period, it is selected for syncing. We then create a new record in the target platform (for example, a new order).

Sync for Commerce also uses id to identify unique records. If we pick up records already received previously, and their ids and sourceModifiedDate match the existing records, we discard these from the sync scope.

If the sourceModifiedDate of the record is different from the previously received one, Sync for Commerce recognizes this as a modified source record and applies these changes as an adjustment.

You can also start a sync manually using our Latest Sync endpoint, or learn more about initiating it. Alternatively, you can read more about sync periods and the sync schedule.