How the API throttle limit works:
The above error occurs when you have exceeded your API key request allowance. The API key as standard is limited to 50 requests per minute. The API key request allowance operates on a rolling minute so that when a request is taken out of the allowance, it takes a minute for the request to return to the allowance, for example:
- 0 seconds – a request is submitted – 49 requests remaining.
- 30 seconds – a request is submitted – 48 requests remaining.
- 60 seconds – First request returns to the allowance – 49 requests remaining.
- 90 seconds – Second request returns to the allowance – 50 requests remaining.
How to resolve the issue:
- Firstly, please ensure that the API does not communicate directly with your integration, the API should only be used to populate your storage layer periodically with fresh data. The integration should then communicate with the data stored on the storage layer, and not with the API itself.
- The only exception to this would be when the API is used to submit data into agentOS, such as a tenancy application form or a diary appointment. In this scenario it is fine to communicate directly from the integration to the API in real time.
- Secondly, you will need implement a throttle on your end for the code that handles the API connection. The throttle will need to ensure that repeated requests are not attempted after the error is returned from the API until the API allowance has a chance to replenish, and that the error response does not terminate execution of your code. The simplest way to implement the throttle is to attempt to call the API unrestricted until the API returns the above error, and then when the error is returned catch the error and set a delay that waits 60 seconds before attempting the request again and resuming execution of the API. This ensures the entire API request allowance for the API key has been replenished.
Increasing the API key request allowance:
As standard the API request allowance is 50 requests per minute. If this request limit is causing performance issues, we might be able to increase the API request rate. The information required to determine whether it is possible to increase your API request limit are as follows:
- Whether your importer job completes successfully or if the error prevents it. If the error prevents it from completing successfully you will need to improve your throttling code so that the error is handled. The error code should not cause the integration to fail to run, and we will not be able to increase the API request limit until the exception is handled correctly on your end.
- The frequency you import data from the API.
- How long the task takes to run completely.
- The last 5 digits of the API key being used.
- Your contact email to reply.
If you believe that the API request limit needs to be increased, please complete our Request API Allowance Increase Application Form.