What do the Xero error codes mean on my invoices?

As an admin, learn how to troubleshoot common Xero error messages

Sarah L. avatar
Written by Sarah L.
Updated over a week ago

Xero is a great tool used to help organize your accounting details and Optix invoices. Once installed, the integration works to sync your users' invoices to your Xero organization. If Optix detects an error, your invoice will be tagged with ‘Xero-error’. All other successfully synced invoices will be tagged as ‘Xero-sync’.

To resolve any “Xero-error' invoices, you’ll first need to refer to the invoice’s transaction history. Select an invoice and you’ll find the transaction history at the bottom of the page if at least one attempt has been logged.

The Optix Team has identified a few error codes from Xero, and have included steps to resolve said errors below:

Error Messages



“Cannot sync invoices with removed payments/credits”

Xero does not allow alterations to paid invoices from within Optix.

Nothing can be done to sync this invoice properly

“Cannot unvoid invoices in Xero”

Xero does not have the capabilities to restore a voided invoice.

Nothing can be done to sync this invoice properly

“Cannot create voided invoices in Xero”

Xero cannot map void Optix invoices into your organization.

Nothing can be done to sync this invoice properly

“API Limit has been reached”

Xero syncs Optix invoices into your account at a certain rate. If there are a large number of invoices syncing at once (perhaps on a billing day), Xero may not be able to process every invoice.

Optix will try to resync the invoice on your behalf. If the invoice has yet to automatically sync, you can manually resync the invoice.

“Error saving contact. There is another contact using the same email, please check Xero contact […]”

Optix only allows one contact per email address.

If an individual has a personal Optix account and is also a team admin (and invoices are sent to the same email address), Optix will not be able to properly create a new contact for the team in Xero.

Change the team’s email address in Optix, and ensure the updated email address does not already exist in your Xero organization.

“Error saving contact. There is another contact using the same name, please check Xero contact [...]”

If no contact with a certain name is found, we'll create a new Xero contact.

If there is an error, there is likely an existing Xero contact with the same name, but a different email.

Hence, Xero will not use this name and will not sync to an invoice.

Rename the user/team either in Optix or Xero to prevent contact names from overlapping.

“Error saving contact. Please restore the archived Xero contact […]”

If your Optix user has an existing Xero contact affiliated with their email address (active or archived), Optix will not be able to map the Xero contact to this user.

Example: Adding back a deleted user to Optix using the same email address, or attempting to create an Optix user for an archived Xero contact.

Go into your Xero organization and either:

a) change the email address affiliated
with the previous user’s contact, or

b) restore the contact

This way, when manually re-syncing, a new Xero contact can be created for the current user.

A validation exception occurred (Account code or ID must be specified) Validation errors: The TaxType field is mandatory

The mapping in Xero Accounts Setting is incomplete and requires an account ID.

Configure the missing default mapping for check-ins, sales, passes, and manual invoice items. You'll need to select an active Revenue or Liability Xero account.

Once you mapped the Xero accounts, manually export invoices to Xero.

A validation exception occurred (Additional people cannot be added when the primary person has no email address set) Validation errors: Additional people cannot be added when the primary person has no email address set.

The team does not have a billing email saved under the account.

The team will need to have a billing email saved under their account.

If the status of this invoice is Void or Paid, please reach out to support@optixapp.com.

Need more info on Apps, Integrations & Payment Gateways?

Did this answer your question?