Rate limiting (error 429)

January 4, 2023


Rate limiting is a protective feature that Erply uses in all APIs. If too many requests have been sent from one IP address in a given time frame, the services will temporarily respond with HTTP status code 429 Too Many Requests.

The purpose of rate limiting is to protect Erply users from denial-of-service attacks (where a malicious actor tries to make services inaccessible to users, by flooding the services with requests). Occasionally though, it might be a well-meaning but misconfigured API integration that triggers the protection by sending server requests in a rapid sequence.

In case an integration has triggered the rate limitation, the same error (429 Too Many Requests) might also be seen when accessing Erply back office.

What triggers a rate limit?

There are two restrictions currently in place:

  1. At most 10 requests are simultaneously allowed from one IP address. If the web server is already processing 10 requests from the same IP, all additional requests will return HTTP status code 429 Too Many Requests.
  2. Within each 30-second time window, the server will accept at most 150 requests from one IP address. When this number has been exceeded, the server will reject all subsequent requests from that IP address with HTTP status code 429 Too Many Requests. The block will last for 10 seconds.

Erply may adjust these settings as needed, without any prior notice.

What to do in case of error 429?

Please wait a few minutes to see if the issue disappears on its own. As shown above, the restrictions are temporary and last for a short period of time only.

If the issue persists or re-occurs, please try to identify source of the issue — the API integration that is making large numbers of requests to Erply servers.

Development suggestions

If you are the developer of the integration or the plugin that is triggering/encountering the 429 error, here are some recommendations to resolve the issue:

  1. Develop your API adapter class so that it would recognize HTTP status codes, and status code 429 in particular. When receiving the error:
    1. If appropriate, let the script wait for 10 seconds and retry.
    2. If not, log an error and save the script's state so that the operation could be re-run at a later time.
  2. Note that the limit is applied per IP address (not per Erply account). If development or maintenance work is disrupting production systems, consider running them from different IP addresses.
  3. If the situation keeps re-occurring:
    1. If your script is multi-threaded, reduce the number of threads;
    2. If the API calls from your server to Erply API have a low latency (so that even a single-threaded script triggers the rate limit), consider introducing occasional short pauses to the script.

Other similar features

Rate limiting is one of the two restrictions that an API client can encounter. The other is the hourly quota of requests, used in Erply API (error 1002).