Rate limits
The InstaVM API limits how fast you can call some endpoints and how many VMs you can run at once. Every limit answers 429 Too Many Requests. This page lists each limit, its scope, and how to retry. The numbers are today's values and can change; handle a 429 whenever it comes.
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{"detail":"Rate limit exceeded. Maximum 60 requests per minute allowed."}
Only one of these limits sends a Retry-After header; the table marks it. When a 429 has no Retry-After, back off exponentially.
Limits at a glance
| Limit | Scope | Number | Retry-After |
|---|---|---|---|
| Requests per minute, per account | Your account, all API keys together | Set by your plan; 60 for an account with no active subscription | No |
| Requests per minute, per address | Your IP address, each endpoint separately | Per endpoint, below | No |
| Concurrent VMs | Your account | Set by your plan | No |
| Concurrent VM startups | Your account | Set by your plan; 1 on the Free plan by default | 15 seconds |
| VM boots per second | Your account | 3 per second by default; 5 on Pro and Enterprise | No |
| Share links | Your IP address, across all share hosts | 20 per second, bursts of 200 | No |
Two endpoints return your account's numbers:
GET /v1/users/mereturnsvm_usagewithactive_vms,max_concurrent_vms,remaining_slotsandmax_concurrent_vm_startups.GET /v1/billing/plansreturnsapi_rate_limit_per_minuteandmax_concurrent_vmsfor each plan.
curl https://api.instavm.io/v1/users/me \
-H "X-API-Key: $INSTAVM_API_KEY"
Requests per minute, per account
These endpoints share one budget per account, across all of its API keys:
POST /v1/vms,POST /v1/vms/{vm_id}/clonePOST /v1/sessions/sessionPOST /execute,POST /execute_asyncPOST /upload,POST /downloadPOST /v1/snapshots,DELETE /v1/snapshots/{snapshot_id}- some tape and recording endpoints
The budget is your plan's api_rate_limit_per_minute. An account with no active or trialing subscription gets 60. The window slides: the API counts your calls to these endpoints over the last 60 seconds. A rejected call does not count.
{"detail": "Rate limit exceeded. Maximum 60 requests per minute allowed."}
Other endpoints do not count against this budget.
Requests per minute, per address
Some endpoints also have a limit per client IP address, counted separately for each endpoint. The table shows today's limit for each.
| Endpoint | Per minute |
|---|---|
POST /v1/snapshots | 10 |
GET /v1/snapshots, GET /v1/snapshots/{snapshot_id} | 500 |
DELETE /v1/snapshots/{snapshot_id} | 30 |
POST /v1/shares | 10 |
PATCH /v1/shares/{share_id} | 30 |
POST /v1/egress/session/{session_id}, POST /v1/egress/vm/{vm_id} | 30 |
GET /v1/egress/session/{session_id}, GET /v1/egress/vm/{vm_id} | 120 |
Over the limit, the API answers:
{"detail": "Rate limit exceeded. Please try again later."}
Concurrent VMs
Your plan sets how many VMs can be active at once (max_concurrent_vms). Suspended VMs do not count. The limit is checked whenever a request needs a new VM: POST /v1/vms, POST /v1/vms/{vm_id}/clone, POST /v1/sessions/session, and POST /execute, POST /execute_async, POST /upload or POST /download on a session that has no VM yet.
{"detail": "VM limit reached (5/5). Stop or suspend a VM, or upgrade your plan for more concurrent VMs. This request was not queued."}
POST /v1/sessions/session puts Cannot create session: in front of the same message.
Waiting does not clear this limit. Stop or suspend a VM, then retry.
Concurrent VM startups
POST /v1/vms also limits how many creates can be in progress at once for your account (max_concurrent_vm_startups). By default this is 1 on the Free plan and 2 on other plans. Over it, the API answers 429 with Retry-After: 15:
{"detail": "Your plan allows one VM or Devbox startup at a time. Wait for the current startup to finish and check its status before retrying. This request was not queued."}
VM boots per second
When POST /execute or POST /execute_async has to boot a new VM, the API limits how many it boots per second for your account. By default a request that gets a pre-booted VM does not count, and a session that starts from a snapshot always does. The default limit is 3 per second, and 5 per second on Pro and Enterprise plans.
{"detail": "VM spawn rate limit exceeded. Maximum 3 VM spawns per second allowed. Please wait before creating more VMs."}
Share links
Requests to share links (*.instavm.site) are limited per client IP address, across all share hosts: 20 requests per second, with bursts of up to 200. Over that, the proxy answers 429 before the request reaches the VM. The body is an HTML page, not JSON, and there is no Retry-After header.
Retrying a 429
Wait, then retry with exponential backoff and some random jitter. Rejected requests do not use up your per-account budget, so short backoffs recover quickly. Do not retry a concurrent-VM 429 in a loop: it clears only when one of your VMs stops or suspends.
import random
import time
from instavm import InstaVM, RateLimitError
client = InstaVM("instavm_sk_...")
def with_backoff(call, attempts=5):
for attempt in range(attempts):
try:
return call()
except RateLimitError:
if attempt == attempts - 1:
raise
time.sleep(min(2 ** attempt, 30) + random.random())
vms = with_backoff(client.vms.list)
What the SDKs retry on their own
Python SDK (0.26). max_retries defaults to 0: no retries. With max_retries=N, the SDK retries 5xx responses, timeouts and connection errors up to N times, waiting 1, 2, 4, ... seconds. It never retries 401, 403 or 429, and it does not read Retry-After. It retries every method, so a retried client.vms.create() can start a second VM and a retried execute() can run the command twice.
JavaScript SDK (0.17). maxRetries defaults to 3, and a value of 0 is also treated as 3. The SDK retries 429, 5xx, timeouts and connection errors, waiting retryDelay (default 1000 ms) doubled on each attempt, with jitter, up to 30 seconds. It retries every method, including VM creation and code execution. RateLimitError.retryAfter is the Retry-After header in seconds, or 60 when the response has none.
See Errors for which requests are safe to repeat.