API clients are subject to two kinds of limitations:

  1. Rate limit;
  2. Hourly request limit.

Rate Limit

Rate limiting is controlled by frontend servers. 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.

The purpose of these limits is to protect Erply users from denial-of-service attacks (where an attacker could make services inaccessible to users, by flooding the services with requests).

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

Development Suggestions

  1. Develop your API adapter class so that it would recognize HTTP status codes, and status code 429 in particular.

    When receiving the error:

    • If appropriate, let the script wait for 10 seconds and retry.
    • 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 your production systems, consider running them from different IP addresses.

  3. If the situation keeps re-occurring:

    • If your script is multi-threaded, reduce the number of threads;
    • 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.

Hourly Limit

Hourly limit is the maximum number of API calls allowed from one Erply account per hour.

The purpose of this limit is to establish a fair usage quota and encourage developers to optimize their applications.

By default, the limit is 3000 requests per hour per account. When you reach the limit, all API calls will return API error code 1002 until the beginning of next hour.

Development Suggestions

  1. Pack multiple API calls into a "bulk request". Bulk requests are "cheaper"; within a bulk request, each call is counted with a coefficient of 0.1. Thus, a bulk request containing 20 calls counts towards the limit the same way as 2 regular calls. (A bulk request can contain at most 100 calls.)

  2. Consider if there is an aggregate API call that fulfills the same purpose. For example, instead of fetching sales documents individually, API call getSalesReport may provide what you need.

  3. You can submit a request to have the limit raised for your account. We review these requests on a case-by-case basis. Please include details of what exactly are you building and what calls you are making; if we see any optimization paths that might benefit you, we'll suggest those.

    Typically, there is no reason to set the hourly limit higher than 10,000.

API calls from point of sale applications (Berlin POS, for example) are counted separately, and do not reduce the quota available to other integrations.