When Xemplo syncs data with Xero (timesheets, payroll, invoices and contacts), Xero occasionally rejects the request and returns an error. This guide covers the errors your users are most likely to see, what they mean, and how to fix them without raising a ticket.
Before troubleshooting a specific error: check the Xero status page and Xero API status page - if Xero itself is experiencing an outage, no fix on the Xemplo side will help; the sync will simply need to be retried once Xero is back online.
Connection & authentication errors
| Error | What it means | Fix |
|---|---|---|
| Session expired / "TokenExpired" / "Unauthorised" | The connection between Xemplo and Xero has timed out - happens automatically after inactivity, or if the user was connected to multiple Xero organisations in one session. | Re-authorise the connection via Xemplo's Xero integration page. |
| "invalid_grant" | Xero's authorisation code or refresh token couldn't be used - usually because it expired, was already used, or the user's Xero credentials changed (e.g. password reset, MFA re-enrolment). | Re-authorise the connection via Xemplo's Xero integration page. This is the only fix; the old token can't be recovered. |
| "You do not have sufficient access" | The Xero user who connected the integration doesn't have the right permission level in that Xero organisation. | In Xero, an admin needs to change that user's role to Standard or Adviser (Settings > Users). Basic-access users can't authorise API integrations. |
| "Invalid EmployeeID" (with multiple Xero orgs connected) | Xemplo is pointed at the wrong Xero organisation. | Check the organisation selector in Xemplo's Xero settings and select the correct one before re-syncing. |
| Rate limit exceeded (HTTP 503) | Xero limits API calls to 60 per minute and 5,000 per day per organisation. This is a Xero-side limit, not a Xemplo fault. | Wait a few minutes and retry. If this happens often during large bulk syncs, space out large timesheet or invoice batches rather than submitting them all at once. |
Timesheet & payroll sync errors
| Error | What it means | Fix |
|---|---|---|
| "Earnings Rate does not exist or is not valid for timesheets" | The pay item linked to the employee has been made inactive in Xero, or replaced with a different rate. | In Xero, go to Payroll Settings > Pay Items, show inactive items, and reactivate the correct rate - or update the employee's Ordinary Earnings Rate under Payroll > Employees > Employment, then retry the action in Xemplo. |
| "Provided period doesn't correspond with a pay period" / "End Date doesn't correspond with a pay period" | The date range being submitted from Xemplo doesn't line up with the employee's payroll calendar in Xero. | In Xero, confirm the employee's assigned payroll calendar (Payroll > Employees > Employment tab) and that calendar's start/end dates (Payroll Settings > Calendars). |
| "This timesheet already exists, please provide the timesheet ID" | A timesheet for that employee and period already exists in Xero, usually from a previous sync attempt. | In Xero, go to Payroll > Timesheets, open the employee's existing timesheet, and delete it before re-syncing from Xemplo. |
| "TrackingItemID is required for each timesheet line" | Xero has tracking categories switched on for timesheets, but Xemplo hasn't been told which tracking option to use. | Either link the correct tracking category in Xemplo via user settings for the consultant linked to the Assignment, or turn the tracking category setting off in Xero (Payroll Settings) if it isn't needed. |
| "Tracking Option does not exist" | The tracking category linked in Xemplo has since been renamed, deleted, or deactivated in Xero. | Re-check that the tracking category is active in Xero and re-select it in Xemplo via the consultant's user account settings. |
| "No timesheets to submit to Xero" | Usually one of three causes: the employee isn't assigned to a payroll calendar in Xero, the employee wasn't synced correctly (missing Payroll ID or Earnings Rate), or there's no approved time in the selected date range. | Check the employee's payroll calendar assignment in Xero and re-sync from Xemplo, and confirm timesheets were approved for that period. |
Invoicing & contact sync errors
| Error | What it means | Fix |
|---|---|---|
| "A validation exception occurred" (generic) | Xero's umbrella error for a failed record - the useful detail is always in the text immediately after it (e.g. "Account code or ID must be specified"). | Always read the full message rather than just the heading, then match it against the specific errors below. |
| "Contact Name is already assigned to another contact" / duplicate contact errors | Xero won't allow two contacts with the same name - usually means the same customer or employee exists twice in Xero. | In Xero, merge the duplicate contacts (Contacts > All Contacts > select both > Merge), keeping the one Xemplo is linked to. |
| "The contact has been archived" | The invoice or timesheet is trying to sync against a Xero contact that's since been archived. | Restore the contact in Xero (Contacts > search with "Include archived" > Restore), then retry the sync. |
| Account code / tax rate errors ("Account must be valid", "Account code or ID must be specified") | The account code on the invoice line is missing, archived, or the linked tax rate doesn't match what's configured against that account in Xero. | In Xero, confirm the account exists, is active, and has a tax rate assigned that matches Xemplo's configuration (Accounting > Chart of Accounts). |
| "Invoice not of valid status for modification" | Xemplo is trying to update or resend an invoice that's already been voided, deleted, or paid in Xero, or a duplicate invoice/reference number already exists. | Check Xero for an existing invoice with the same number or reference (including voided ones). |
| "The invoice you are trying to allocate to has already been paid off" | A payment is being synced against an invoice that's already fully paid or closed in Xero. | In Xero, check whether a payment or credit note has already been applied. If it was applied outside Xemplo, unapply it in Xero or skip re-syncing that payment. |
When to escalate to Xemplo support
Most of the above are configuration issues on the Xero side and can be self-resolved. Raise a ticket instead when:
- The error message doesn't match anything in this list
- The Xero status page shows no outage but the same error persists after following the fix above
- The same error affects multiple employees/contacts at once, which usually points to a mapping issue in Xemplo rather than Xero