Limits keep the platform responsive for everyone. They are generous for normal automation; a well-behaved integration rarely meets them.
Account limit
120 requests per minute per account. The limit is shared by all tokens of the account: more tokens do not give more requests.
Every answer to a request that was counted carries the state of this limit:
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117Requests refused before they are counted answer without these headers: an unknown token (401), an address or account that is not allowed (403 forbidden), the API switched off (503 api_disabled), and the 429 of this limit itself.
Limits per IP address
Before the account limit, requests are counted per IP address they come from, whatever the account:
- a steady rate of up to 5 requests a second, with short bursts of about 20 requests at once;
- at most 10 connections open at the same time.
A request above these is refused before it reaches your account, so it carries no X-RateLimit-* or Retry-After headers. Slow down and retry after a second or two. Spread parallel work over time rather than sending it all at once.
Per-server limits
On top of the account limit, some requests are counted per server. A busy server does not slow down the other servers of the account.
| What | Limit |
|---|---|
Live reads: status, stats, traffic, rdns, backups |
30 per minute per server |
Every change of a server, and guest-agent |
10 per minute per server |
Ordering servers (POST /services/virtual-servers) |
10 per minute per account |
The X-RateLimit-* headers always show the account limit, not these.
Limits of single actions
Some actions are expensive or disruptive, so they have limits of their own per server, most of them per hour:
| Action | Limit |
|---|---|
| The same power action again | after 15 seconds; stop and reset after 30 seconds |
| Saving SSH keys (both ways together) | 10 per hour |
| Opening the console | 30 per hour, at most 5 consoles open at once |
| Reinstalling | 3 per hour |
| Creating a backup by hand | 2 per hour |
| Restoring from a backup | 3 per hour |
| Deleting backups | 10 per hour |
When a limit is reached
The answer is 429 with the code rate_limited. How long to wait depends on the limit:
| Limit | How the answer says when to retry |
|---|---|
| Account limit | the Retry-After header in seconds, also given as retry_after in the error |
| Per-server and order limits per minute | the Retry-After header in seconds |
| Hourly limits of single actions | no header: message says in how many minutes the action is possible again |
| The same power action again | no header: retry after the pause in the table above (15 or 30 seconds) |
| Limits per IP address | no header: retry after a second or two |
HTTP/1.1 429 Too Many Requests
Retry-After: 23
{"error": {"code": "rate_limited", "message": "Too many requests.", "retry_after": 23}}Wait at least Retry-After seconds before the next attempt when it is given. Do not retry in a tight loop: requests refused by a limit still count.
Good practice
- Do not poll faster than you need. The server status is cached for a few seconds, so polling it every second gives nothing. Every 5 to 10 seconds is plenty while you wait for a server to start; for a long operation such as an order or a reinstall, every 15 to 30 seconds.
- Read lists, not every server.
GET /services/virtual-serversreturns all your servers with their status in one request. - Cache what rarely changes, such as the catalog and the OS templates.
- The limits above are the current values and may be adjusted. Read the headers and
Retry-Afterrather than hard-coding the numbers.