Xero API Limits, Errors & Best Practices (So You Don’t Get Blocked)

When integrating with the Xero API, hitting a wall as also called as a “429 error” is every developer’s worst nightmare. Whether you’re building a custom integration, invoices syncing, or creating a dashboard for business, understanding the limits of the Xero’s API and error handling is important for smooth performance.

In this blog, we will break down rate limits, common errors, and the best practices of the Xero so you can follow to keep your integration stable, effective, and out of any issues.

Xero API Rate Limits Explained

Xero API is a strong, yet like any SaaS API, it also has its own default rate limits to ensure stability of the platform. Here is the information that you need to know:

• Daily limit:
  • 1,000 API calls per connected organisation, per app.
• Per-minute throttling:
  • To prevent sudden traffic crashes, Xero also applies short-term rate limits. If you exceed the burst limit, you will receive a 429 Too Many Requests error.

You can track your usage by headers returned in the API response as outlined in the Xero API Rate Limits documentation, such as:

• x-rate-limit-remaining: 200
• x-rate-limit-limit: 1000

Tip: Monitor these headers and pause requests when you are near to the limit.

Common Xero API Errors (And What They Mean)

Understanding API errors makes troubleshooting far easier to handle. Here’s a quick guide:

Tip: Always log the full error response body to help debug faster.

Best Practices to Avoid Getting Blocked

Now for the good stuff: What are actions that you need to follow to keep your Xero integration smooth and compliant.

1. Use Exponential Backoff

If you get a 429 or 500 error, don’t retry immediately. Implement a backoff algorithm to cause you to wait longer before retrying.

2. Cache Where You Can

If you are trying to retrieve the same data frequently (e.g., chart of accounts, contact info), cache it. Reduce unnecessary API calls.

3. Batch Requests

Where possible, group a number of tasks into a one call. This reduces API usage significantly.

4. Monitor Usage

Set up notification based on your remaining daily quotas with the x-rate-limit-remaining header. Do not fly blind.

5. Refresh Tokens Proactively

Xero uses OAuth 2.0, so tokens will expire eventually. Make sure your app refreshes tokens in advance of when they will expire. You can follow the official  Xero OAuth 2.0 Guide.

6. Use Webhooks Instead of Polling

If available, use webhooks to receive notification of updates instead of repeatedly use the API calling to check for any changes.

Tools & Resources to Help

• Xero Developer Portal
• SDKs: Xero provides official libraries for Node.js, Python, PHP, and more
• API testing: Use Postman or Insomnia for safe testing
• Monitor with tools like Datadog or Custom Dashboards

Example

You are syncing invoices every 10 minutes across for number of organisations. Suddenly, you start getting 429 errors. A quick audit shows you were making 50+ calls per organisation per hour, which is way over the budget.

How to fix: You implemented smart caching + reduced polling intervals, and then there will be no more errors, and your sync is even faster.

Conclusion

Xero’s API is rock solid, but it is very important to respect the limits and build your integration with care. By understanding the most common errors and following best practices, you will avoid being blocked and ensure your users have a smooth experience.

Need Help with Your Xero Integration?

Whether you’re building something custom or trying to fix an existing platform with Xero, we can help. We have experience professional who deal with all kinds of situations in XERO API integration with software development. Let’s chat about how to build a seamless, scalable platform with integration Xero for your business.