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.
- Adding time entries in FYI.
- 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.
For example:
- 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 and the rate limits have been exhausted, Practice Activity will display the following message:
- "(Sync) failed due to rate limiting."
Viewing Rate Limits
When using the Xero Practice Manager Automation App, or using Client or Job Bulk Update, FYI will provide details on the current rate limits:
- The number of available requests remaining.
- The estimated number of requests to be used by Bulk Update.
- The time until the next refresh (if the rate limit has been reached).
- When the data was last refreshed (Xero Practice Manager app only).
Available Requests remaining
FYI displays the approximate number of remaining available requests, useful for avoiding hitting the rate limits.
Estimated Requests
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 or Resubmit 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:
- For practices on the Elite plan, when selecting FYI as your Practice Management solution, FYI will be automatically enabled as the Primary Source of Client Data. This allows FYI to become the main source for creating and managing your clients. Updates to clients will be available instantly, and the synchronisation frequency with Xero Practice Manager will be reduced. Refer to Enabling FYI as Primary Source for Client Data and Synchronising with Xero Practice Manager where FYI is enabled for Primary Source of Client Data.
- 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.
Note: If using FYI as the Primary Source of Client Data, this setting is not available. - 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).
- Changing your Practice Settings to select the XPM Staff Allocation method of "Inherit from Job". This will reduce the number of synchronisations performed when creating time in FYI, but users will need to be manually assigned to Jobs in XPM before the time is submitted. Refer to Managing Practice Settings
When synchronising jobs older than 24 months, FYI uses a request to check the status of the job to confirm if it has been deleted or there has been a change to the Job State. If there is only a small number of remaining requests available, FYI will cancel the synchronisation to reserve those requests for higher priority requests.
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.