XERO Errors
Let’s Dive in to see types of XERO Errors.
How to fix Xero Errors?
QuickFix Bookkeeping has crafted some DIY resources to help you with Xero errors.
Our expert team can swiftly resolve these errors, too.
We are just a phone call away.
* All trademarks and logos are the property of their respective owners. Images for visual reference only.
Xero Error Code Decoder — At a Glance
Every Xero error falls into one of three buckets. Knowing which bucket tells you immediately who needs to act.
4xx
Client-side errors
Something about your request is wrong. Your credentials, your permissions, your data format, or your browser cookies. You need to fix something.
5xx
Server-side errors
Something went wrong on Xero's servers. Not your fault. Check status.xero.com, wait, and retry. If persistent, contact Xero support.
2xx
Success responses
Your request worked. 200 = full success. 201 = created. 204 = deleted successfully. No action needed.
Complete Xero Error Code Reference
Detailed causes and step-by-step fixes for every common Xero error code.
Bad Request
The server could not understand your request due to invalid syntax or data
🔥 Most Common Xero 400 Error — "Bad Request — Request Too Long"
Full message: "Bad Request — Request Too Long. HTTP Error 400. The size of the request headers is too long."
This is the most-searched Xero error on this site and the most misunderstood. Despite the scary message, it is almost always a browser cookie problem, not a Xero problem. Your browser has accumulated too many cookies for xero.com and is sending a request header that exceeds the server's size limit. The fix takes under 2 minutes.
Step-by-step fix:
Test first in incognito/private mode. Press Ctrl+Shift+N (Chrome/Edge) or Ctrl+Shift+P (Firefox) and try opening Xero. If it works in private mode — the issue is confirmed as cookies/cache in your regular browser.
Clear cookies specifically for xero.com (not all sites): In Chrome — go to Settings → Privacy and security → Cookies and other site data → See all cookies → search "xero" → delete all Xero cookies. Alternatively press Ctrl+Shift+Delete → select Cookies → All time → Clear data.
Restart your browser completely (close all windows, not just the tab) and try logging into Xero again.
Still failing? Try a different browser entirely (Chrome vs Firefox vs Edge). Also disable any browser extensions that might add headers (password managers, SSO tools, privacy extensions).
QuickFix tip: If this error recurs regularly for the same user, they likely have browser extensions that inject cookies or headers on every request. Identifying and removing the offending extension permanently resolves it. SSO and corporate identity management extensions are the most common culprit.
Other Xero 400 Bad Request causes:
Invalid data format (API)
A field in your API request is malformed — wrong date format, missing required field, or incorrect data type. Xero's 400 response body contains a ValidationErrors array — read it carefully, it tells you exactly which field is wrong.
Invalid redirect URI (OAuth)
The redirect URI in your OAuth request does not exactly match one registered in your Xero app settings. Even a trailing slash difference causes this. Verify the URI character-for-character in your Xero developer app dashboard.
Duplicate invoice number
Xero returns 400 when you try to create an invoice with a reference number that already exists. Change the invoice number or check your duplicate detection logic.
Invalid account code
The account code referenced in a transaction does not exist in the Xero chart of accounts for that organisation. Verify the account code is correct and active before posting the transaction.
Unauthorized — AuthenticationUnsuccessful
Your authentication credentials are missing, expired, or invalid
Error 401 means Xero cannot verify who you are. Unlike 403 (which knows who you are but denies access), 401 means the authentication itself has failed. The most common cause is an expired OAuth 2.0 token — Xero access tokens expire after 30 minutes, and refresh tokens expire after 60 days if unused.
For everyday Xero users
Log out of Xero completely — go to your profile icon → Sign out. Do not just close the tab.
Clear cookies for xero.com (same steps as the 400 fix above) and close all Xero tabs.
Navigate to login.xero.com and log in fresh. Do not use a bookmarked deep URL.
For integrations / API connections
Check that your access token has not expired (30-minute lifetime). Use the refresh token to obtain a new access token before it expires.
If the refresh token has expired (unused for 60+ days), the full OAuth flow must be re-run. Re-connect via your integration's settings page.
Check that the Xero user who granted access has not been deactivated or removed from the organisation — their credentials power the token.
QuickFix tip: A 401 that appeared suddenly — without any action on your part — often means the Xero user account that originally authorised the connection has been deactivated, had their password reset, or had MFA added. Any of these events invalidates the OAuth tokens. Check your Xero Organisation → Users list for the account that set up the connection.
Forbidden
Xero knows who you are — but you don't have permission to do this
Error 403 is different from 401. You are authenticated (Xero knows who you are) but you lack the permission to perform the specific action. This is a role or scope problem.
Wrong Xero user role
The Xero user's role (Adviser, Standard, Invoice Only, Read Only) does not permit the action. A Standard user cannot access payroll, for example. Check Settings → Users → their role in Xero.
Missing OAuth scope (API)
Your OAuth app did not request the required scope during authorisation. For example, accessing payroll requires the payroll.read or payroll.employees scope. Re-authorise requesting the correct scopes.
Organisation access not granted
For multi-tenant apps, the user authorised the app for a different Xero organisation. The Tenant ID in your API requests must match an organisation the user has granted access to.
401 vs 403 — the key difference: If you can log into Xero and see the organisation but get 403 on a specific action — it is a permissions problem (role or scope). If you cannot log in at all or your token is rejected — it is a 401 authentication problem.
Not Found
The resource, record, or page you requested does not exist
Error 404 means the specific resource you requested — an invoice, a contact, a page URL — does not exist in Xero. Either the ID is wrong, the record was deleted, or you are accessing the wrong organisation.
404 on a Xero page
Log out completely, clear cookies, and navigate to xero.com fresh. A 404 on a Xero URL often means your session is sending you to an organisation or region you no longer have access to. Try accessing Xero via go.xero.com rather than a saved link.
404 on API request
The record ID in your request does not exist in this organisation. Verify the GUID is correct and that you are querying the right Xero tenant. Also check if the record was deleted — Xero uses soft deletes and deleted records return 404.
Too Many Requests — Rate Limit Exceeded
You have exceeded Xero's API rate limits
Xero's API has rate limits: 60 API calls per minute per app per organisation, and a daily limit of 5,000 calls. When exceeded, all calls return 429 until the rate window resets.
Immediate fix
Stop all API calls and wait. Check the Retry-After header in the 429 response — it tells you exactly how many seconds to wait before retrying. The per-minute window resets after 60 seconds.
Permanent fix
Implement exponential backoff in your integration — when you receive a 429, wait progressively longer before each retry. Cache responses where possible. Batch API calls rather than making individual calls for each record.
Internal Server Error
Something went wrong on Xero's servers — not your fault
A 500 error means Xero's servers encountered a problem they did not know how to handle. The error originates entirely on Xero's side. No amount of local troubleshooting will fix a genuine Xero 500 error — the only action available to you is to wait and retry.
What to do when you get a 500
Check status.xero.com immediately. If Xero is reporting an incident, wait for their engineering team to resolve it — no local fix will help.
If status.xero.com shows all green — try logging out and back in, clear cookies, and retry after 5-10 minutes. Transient 500s often resolve on their own.
For API integrations: Before assuming the error is entirely on Xero's side, double-check your request payload. A highly unusual data format can occasionally trigger an unhandled server exception that surfaces as 500. Validate all required fields, data types, and date formats.
If 500 persists for more than 30 minutes and status.xero.com shows no incident — contact Xero support with the specific API endpoint, timestamp, and request details so their team can investigate.
500 vs 503: Both are server-side. A 500 means Xero's server encountered an unexpected error processing your request. A 503 means Xero's service is temporarily unavailable — either overloaded or offline for maintenance. The response to both is the same: check status.xero.com and wait.
Service Unavailable / Organisation Offline
Xero's service is temporarily down or the organisation is offline
Xero returns 503 in two distinct scenarios — and the response is different for each:
503 — Xero service unavailable
Xero's servers are under heavy load or down for maintenance. Action: Check status.xero.com, subscribe to their status notifications, and wait. Planned maintenance is usually announced in advance via status.xero.com.
503 — Organisation offline (API)
For API integrations: the specific Xero organisation your request targets is offline — usually because it is in a financial year-end roll-over or an administrator has taken it offline. Action: Wait and retry with exponential backoff. The response body will contain "Organisation is not currently available".
QuickFix tip: For integrations that cannot afford downtime, build a queue-and-retry system around Xero API calls. When you receive a 503, place the request in a queue and retry with exponential backoff (wait 5s, then 10s, then 20s, etc.). This is far more resilient than immediately surfacing the error to the user.
Xero-Specific Errors (Not HTTP Codes)
These are error messages that appear within Xero itself — in the interface, on reports, or in bank reconciliation.
"Sorry, something went wrong"
Generic Xero interface error. First check status.xero.com. If Xero reports no issues: clear cookies (especially xero.com cookies), log out fully, close all Xero tabs, wait 5 minutes, then log in fresh at login.xero.com. If it persists on a specific page, try the same action in a different browser.
Clear cookies → retry"Connection to bank is broken" / Bank feed error
Your bank feed connection in Xero has expired or the bank changed their authentication requirements. Go to Accounting → Bank Accounts → the affected account → Manage Account → Refresh Bank Connection. Re-enter your bank credentials. Some banks require this refresh every 90 days.
Reconnect bank feed"This invoice has already been paid"
You are trying to apply a payment, credit note, or allocation to an invoice that is already marked as paid. Check the invoice's payment history — there may be a duplicate payment or an automated bank reconciliation that already matched it. Void the incorrect payment to make the invoice available again.
Check payment history"The tax rate you entered is not valid"
The tax rate code used in a transaction does not exist or is not applicable to the account type. Go to Accounting → Tax Rates and verify the tax rate exists and is active. For API integrations, the TaxType field must exactly match a valid tax type from your organisation's Xero settings.
Verify tax rate settings"Invalid scope for client" (OAuth error)
Your OAuth application is requesting a permission scope that is not allowed for its app type, or the scope name is spelled incorrectly. Common for custom integrations. Verify the exact scope names in Xero's developer documentation — they are case-sensitive. Re-authorise after correcting the scope list in your application.
Verify OAuth scopes"Cannot reconcile — amounts don't match"
A bank transaction amount and the invoice/bill amount do not match exactly (including currency differences, bank fees, rounding). In Xero's reconciliation screen, use the "Find & Match" function to split the transaction or create a reconciliation adjustment. Do not force a match — the difference needs to be coded to a bank charges or write-off account.
Use Find & MatchPreventing Xero Errors — Best Practices
For everyday Xero users
Bookmark login.xero.com rather than deep URLs — session-linked URLs go stale.
Clear Xero cookies monthly — prevents the "request too long" 400 error from accumulating cookies.
Subscribe to status.xero.com for email/SMS alerts on Xero outages and maintenance windows.
Refresh bank feed connections before the 90-day automatic expiry — don't wait for the error to appear.
For API integrations
Implement token refresh proactively — refresh the access token before the 30-minute expiry, not after you get a 401.
Build exponential backoff retry logic for all 429 and 5xx responses — never fail immediately on a transient server error.
Always read the full Xero error response body — 400 errors include a detailed ValidationErrors array that tells you exactly what is wrong.
Log which Xero user account owns each OAuth token — if that user is deactivated, all tokens from them become invalid simultaneously.
Quick Triage — Got an Error Right Now?
| Your error | Who is responsible | First action | Time to fix |
|---|---|---|---|
| 400 — request too long | Your browser cookies | Clear Xero cookies in browser | 2 minutes |
| 401 — unauthorized | Expired session or token | Log out and log back in fresh | 5 minutes |
| 403 — forbidden | Your role or permissions | Check user role in Xero Settings → Users | Admin needed |
| 404 — not found | Wrong URL, deleted record | Log in fresh at login.xero.com | 2 minutes |
| 429 — too many requests | Your API call rate | Stop all calls, wait 60 seconds, retry | 60 seconds |
| 500 — server error | Xero's servers | Check status.xero.com, wait, retry | Wait for Xero |
| 503 — unavailable | Xero's servers / org offline | Check status.xero.com, subscribe to alerts | Wait for Xero |
Migrating from Xero? — Common QuickFix services
Many businesses experiencing persistent Xero errors consider whether their accounting platform is the right fit. At QuickFix Bookkeeping, we handle migrations between Xero, QuickBooks, MYOB, and other platforms — including clean data migration, chart of accounts mapping, and post-migration reconciliation.