Rate limits

The VMArea Public API uses two stacked buckets, both backed by Redis so the limits are shared across every API instance.

Current limits

Bucket	Limit	Keyed by	Applies to
Public API (per token)	600 requests / minute (10 RPS sustained)	API token ID	Every `/api/public/v1/*` request after `x-api-key` auth succeeds
Global fallback (per IP)	100 requests / minute	IP address	All traffic — primarily catches abuse of unauthenticated routes (login, signup)

The per-token bucket means heavy customers and clients behind shared NAT IPs aren’t penalised for each other’s traffic. Pair this with the Idempotency-Key header so safe retries don’t burn extra requests — see Idempotency.

429 response

When you exceed either limit, the API returns HTTP 429 Too Many Requests:

{
  "success": false,
  "error": "Rate limit exceeded for this API token: 600 requests per minute. Retry after 42."
}

The error string identifies which bucket you tripped (per-token vs per-IP global fallback).

Response headers

Every response includes the standard rate-limit headers; Retry-After is added on 429 responses.

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Seconds until the window resets.
`Retry-After`	Seconds to wait before retrying (only on `429`).

Handling 429 in your client

Read Retry-After for the minimum wait, then back off exponentially with jitter starting at 1 second:

async function requestWithRetry(url, options, maxAttempts = 5) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;

    const retryAfter = parseInt(res.headers.get("Retry-After") ?? "1", 10);
    const base = Math.max(retryAfter, 1) * 1000;
    const jitter = Math.random() * 1000;
    const delay = base * Math.pow(2, attempt - 1) + jitter;
    await new Promise((r) => setTimeout(r, delay));
  }
  throw new Error("Rate limit: max retry attempts exceeded");
}

Best practices

Use Idempotency-Key for writes. Safe retries won’t double-spend your quota or create duplicate resources.
Batch reads where possible. Paginated list endpoints are cheaper than fan-out GETs.
Cache catalog data. Plans, regions, and OS templates change infrequently — cache them locally rather than re-fetching.
Use webhooks for state changes. Subscribing to vm.started, vm.stopped, etc. avoids polling GET /vms/:id in a tight loop.
Need higher limits? Contact support — sustained 10 RPS covers virtually every integration, but we can raise per-token ceilings on request.

Get started

Authentication

API conventions

Resources

Current limits

429 response

Response headers

Handling 429 in your client

Best practices

​Current limits

​429 response

​Response headers

​Handling 429 in your client

​Best practices

Current limits

429 response

Response headers

Handling 429 in your client

Best practices