Skip to main content

Xero API Rate Limiting

Updated

Xero limits API calls, which can affect syncs with Codat. This document will show you how to identify if this affects your integration and steps you can take to mitigate the issue.

Audience

This doc is aimed at technical users that can understand and consume API endpoints.

Pre-requisites

The user will manually call our API endpoints: https://docs.codat.io/reference/using-codats-api-1

Xero API Rate Limiting

The Xero help article: https://developer.xero.com/documentation/guides/oauth2/limits/#api-rate-limits

Xero implements three types of rate limiting against a single tenant:

  • Concurrent Limit: 5 calls in progress at one time
  • Minute Limit: 60 calls per minute
  • Daily Limit: 5000 calls per day

Xero also implements a single type of rate limit against all tenants:

  • App Minute Limit: 10,000 calls per minute

Diagnosis

If your account breaches the throttling limits, error responses will be returned in the response payload.

To query these errors on an ad hoc basis, you can call Codat's companies//data/history endpoint: https://docs.codat.io/reference/get_companies-companyid-data-history

Errors

 "statusCode": 500,
"errorMessage": "Maximum timeout of \"00:02:00\" would be exceeded by delay of \"00:02:00.3867394\" for request to \"Items\".",

This error has been returned because Codat has detected possible breeches of the Concurrent\Minute rate limits.

You will note two numbers. The first is the expected timeout of the rate limit reached. The second is our predicted time when we expect that a retry will execute successfully. See first mitigation step below.

Codat.Integrations.Xero.Core.Exceptions.RateLimits.XeroApiDailyCapReachedFatalException Company (3cefe2f6-dd94-4a99-8c27-a13531c50b69) has reached the daily rate limit cap (retry-after 66975) Void MoveNext() at Codat.Integrations.Xero.Core.OAuthRetryClient.HandleRateLimitResponse(Guid companyId, IServiceRequest request, IServiceRawResponse rawResponse, String response, Int32 retry) in D:\a\1\s\src\Codat.Integrations.Xero.Core\OAuthRetryClient.cs:line 256

This error is returned from Xero for reaching the Daily Limit. The Daily Limit will reset after the retry-after time, shown in seconds.

Mitigation

During a push operation

If the error returned includes the text "would be exceeded by delay of" set the retry timeout for the item to the time specified when submitting your push operation again.

During a dataset sync (or pull operation)

If you frequently reach a throttling limit, you may want to consider reducing the sync frequency. Most data types and use cases can be managed using a combination of daily and weekly frequencies, alongside ad-hoc syncs requests. If you are planning to sync a very large Xero organisation, it may be necessary to restrict the starting date for the sync by adjusting the syncFromUTC value of your sync settings prior to your first sync. 

You can find more information on how to modify these settings here.

------------------------

If you have any questions on the information shared above, contact support@codat.io. 

Powered by Zendesk