Xero - API and Third-Party Integration Error Guide

Xero API Integration Error: Fix Third-Party App Connection Failures

A third-party app connected to Xero is showing "OAuth authentication failed", "Rate limit exceeded", or data is not syncing between Xero and the connected app.

At QuickFix Bookkeeping, Xero API integration errors fall into two categories: authentication failures (the app cannot prove its identity to Xero) and data errors (the app is connected but data does not pass Xero validation). Each has a different fix path.

The QuickFix Bookkeeping Distinction

Xero API errors are either authentication failures or data validation failures -- completely different fixes.

Authentication failure

The third-party app's OAuth token has expired or been revoked. Xero access tokens expire after 30 minutes of inactivity; refresh tokens after 60 days. The app cannot communicate with Xero until re-authenticated.

Data validation failure

The app is authenticated but the data it sends to Xero does not pass validation -- mismatched account codes, missing fields, duplicate invoice references. The HTTP response contains the specific validation error.

Check first: Look at the HTTP response code. 401 = authentication failure (re-authorise). 400 = data validation failure (fix the data). 429 = rate limit (wait and retry). Each code points to a different fix.

What Causes Xero API Integration Errors?

Error code

API ERROR

Xero API - OAuth - Third-Party Integrations

What it means

A third-party app connected to Xero is showing "OAuth authentication failed", "Rate limit exceeded", or data is not syncing between Xero and the connected app.

What Causes This Error?

🔐

OAuth Token Expired or Revoked

The OAuth access token issued by Xero has expired (30-minute lifespan) and the refresh token has also expired (60 days) or been revoked. The app must re-authenticate.

⚡

API Rate Limit Exceeded (Error 429)

The app is making too many API calls. Xero's limit is 5,000 calls per day per organisation and 60 per minute. Exceeding either produces HTTP 429 errors.

📊

Mismatched Account Codes

The app is trying to post transactions to Xero account codes that do not exist in the connected Xero organisation.

🔀

Duplicate Invoice or Bill Reference

The app is trying to create an invoice with a reference number that already exists in Xero. Xero rejects duplicate invoice numbers.

🔒

Xero Organisation Permissions Changed

A Xero administrator changed the permission level of the user whose credentials were used to connect the app. The integration fails for data types that user can no longer access.

Xero API HTTP Error Codes

400

Bad request - data validation failure

401

Unauthorised - token expired or revoked

403

Forbidden - insufficient permissions

429

This page -- Rate limit exceeded - too many calls

How to Fix This Error

METHOD 1Re-Authorise the Third-Party App with XeroOAuth authentication failure (HTTP 401)
1

In the third-party app, go to Settings > Integrations > Xero and find the Disconnect or Re-authorise option.

2

Click Disconnect to remove the expired token.

3

Click Connect to Xero and complete the OAuth flow -- you will be redirected to Xero to log in and grant permission.

4

Select the correct Xero organisation and approve the requested permissions.

METHOD 2Fix Account Code MappingData validation errors (HTTP 400)
1

In the third-party app, go to Settings > Xero Mapping or Account Mapping.

2

For each category (income, expenses, tax, bank), verify the mapped Xero account code exists in your Xero chart of accounts.

3

Open Xero > Accounting > Chart of Accounts and confirm account codes match exactly.

4

Save the updated mapping and manually trigger a re-sync of the failed transactions.

METHOD 3Handle Rate Limiting (HTTP 429)Too many API calls
1

Do not simply retry when getting HTTP 429 -- this makes rate limiting worse.

2

Check the app's sync frequency settings and reduce the polling interval if possible.

3

Implement exponential backoff: wait 1 minute, then 2, then 4, doubling each retry.

4

Contact the app's support team if 429 errors persist -- they may need to optimise their API call patterns.

Related Errors

Xero API Integration Still Failing After Re-Authentication?

QuickFix Bookkeeping Resolves Complex Xero API Integration Issues.

Persistent Xero API errors after re-authorisation usually point to a data mapping problem or permission scope issue requiring examination of the actual API response payload. Our Xero integration specialists diagnose the exact error and fix the integration at the root cause.

Book a Free 30-Minute Consultation

No obligation. Same-day response.