Rate limits were introduced by Xero as part of their OAuth 2.0 change. This means there is a set amount of requests that can be made each day to synchronise data between FYI and Xero Practice Manager.
As these rate limits are set by Xero for app partners, FYI is unable to increase the limit for practices. For more information on these limits, please refer to the Xero article API rate limits and Frequently Asked Questions about Limits.
Synchronisation requests occur during:
- The overnight synchronisation with Xero Practice Manager
- Day-to-day changes made in either FYI or Xero Practice Manager.
- Bulk updates in FYI.
- Manual synchronisations requested from FYI, for example, Clients, Jobs etc.
As each of these synchronisations occur the number of available requests will be reduced.
To understand what data is synchronised and how often, refer to the article Synchronising Clients, Staff, Jobs, Time, Tax Returns with Xero Practice Manager.
Understanding Rate Limiting
Rate limiting can occur when all available synchronisation requests to XPM for the day are exhausted, typically caused by excessive manual synchronisations, or large client or job bulk updates in FYI.
- Bulk updating 10 jobs with one field change per job - 20 separate API requests (one for each job, and one for each field).
- Bulk updating 10 jobs, one field for each job, but three times throughout the day - 60 separate API requests (one per job, one per field, three times a day - 20 for the first change, 20 for the second change, and 20 for the third change).
- Prompting a manual sync for Clients (the number of requests will vary depending on the number of clients in your system)
Rate Limiting Errors
When changes are made in FYI but the rate limits have been exhausted, Practice Activity will display the following message:
- "The error happened because of rate limiting."
Bulk Updates and Estimated Requests
To assist with the management of rate limiting, FYI will display the number of available requests remaining, the estimated number of requests to be used by bulk update, and the time until the next refresh (if the rate limit has been reached).
Available Requests remaining
FYI displays the approximate number of remaining available requests in the Bulk Update drawer. This is useful for tracking the number of requests used to avoid hitting the rate limits.
When bulk updating either Clients or Jobs, multiple requests will be sent to Xero Practice Manager to sync the data.
The Bulk Update Drawer in FYI displays the Available Requests remaining until the next Rate Limit refresh, and the Estimated Bulk Update Requests that will be used by the Bulk Update action.
The Estimated Bulk Update Requests will increase as more fields are selected to be updated for each client or job:
- Client or Job - 1 request.
- Other Fields (Name, Start/Due Date, Budget) - 1 request.
- Partner and/or Manager - 1 request.
- Job State - 1 request.
- Custom Fields - 1 request.
For example, updating a single job with a new Job State, Name, Partner, and Custom Field would be 5 requests. 2 jobs would be 10 requests.
Note: The number of requests is an estimate only. On occasion, there may be additional fields that need to be updated to ensure that data is consistent for both FYI and Xero Practice Manager, identified only when the sync is underway. These requests will not be included in the estimated total.
Rate Limit Refresh Time
Once the available requests have been exceeded, Xero Practice Manager advises the amount of time remaining before the requests will be refreshed.
FYI displays this information in the Bulk Update drawer so that users will be able to plan for their bulk update when more requests become available.
Avoiding Rate Limiting
If a sync fails for any reason an alert will be added to Practice Activity. Once the error has been resolved, users will be able to click Retry to resync the data. Refer to Practice Activity.
The same number of requests will be used in the retry as in the original synchronisation. For example, if the initial attempt used 5 requests, an additional 5 requests will be used in the retry.
To minimise the chance of exhausting the number of requests, and therefore hitting rate limits, we recommend the following:
- Maximise the available API calls for your practice by setting the Sync Custom Fields from XPM option to Off in FYI. Refer to the section "Sync Custom Fields from XPM" in the article Resetting your Connection between FYI and Xero Practice Manager.
- Process changes in smaller quantities over longer time periods.
- Review your automation and process history to ensure there is no looping or duplication of steps (wasting the available API calls).
FYI continues to provide feedback to Xero on the impact these API call limits have on practices using the integration between FYI and Xero Practice Manager.