Limites de taxa

A API pública da VMArea usa dois buckets encadeados, ambos com Redis como backend — os limites são compartilhados entre todas as instâncias da API.

Limites atuais

Bucket	Limite	Chaveado por	Aplica-se a
API pública (por token)	600 requisições / minuto (10 RPS sustentado)	ID do token de API	Toda requisição `/api/public/v1/*` após autenticação bem-sucedida com `x-api-key`
Fallback global (por IP)	100 requisições / minuto	Endereço IP	Todo o tráfego — principalmente para conter abusos em rotas não autenticadas (login, cadastro)

O bucket por token garante que clientes pesados e clientes atrás de NAT compartilhado não penalizem uns aos outros. Combine com o cabeçalho Idempotency-Key para que retentativas seguras não consumam cota extra — veja Idempotência.

Resposta 429

Quando você excede algum dos limites, a API retorna HTTP 429 Too Many Requests com o envelope padrão:

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

A string error identifica qual bucket foi atingido (por token ou fallback global por IP).

Cabeçalhos

Toda resposta inclui os cabeçalhos padrão de rate limit; Retry-After é adicionado nas respostas 429.

Cabeçalho	Descrição
`X-RateLimit-Limit`	Número máximo de requisições permitidas na janela atual.
`X-RateLimit-Remaining`	Requisições restantes na janela atual.
`X-RateLimit-Reset`	Segundos até a janela reiniciar.
`Retry-After`	Segundos para aguardar antes de tentar novamente (apenas em `429`).

Tratando 429 no seu cliente

Leia Retry-After para o tempo mínimo de espera, depois aplique backoff exponencial com jitter começando em 1 segundo:

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");
}

Boas práticas

Use Idempotency-Key para escritas. Retentativas seguras não consomem cota extra nem criam recursos duplicados.
Agrupe leituras onde possível. Endpoints de listagem paginados são mais eficientes do que múltiplos GETs individuais.
Faça cache dos dados do catálogo. Planos, regiões e templates de SO mudam raramente — armazene-os localmente em vez de buscar repetidamente.
Use webhooks para mudanças de estado. Assinar vm.started, vm.stopped etc. evita polling em loop em GET /vms/:id.
Precisa de limites maiores? Entre em contato com o suporte — 10 RPS cobre praticamente todas as integrações, mas podemos aumentar os limites por token sob solicitação.

Comece aqui

Autenticação

Convenções da API

Recursos

Limites atuais

Resposta 429

Cabeçalhos

Tratando 429 no seu cliente

Boas práticas

​Limites atuais

​Resposta 429

​Cabeçalhos

​Tratando 429 no seu cliente

​Boas práticas

Limites atuais

Resposta 429

Cabeçalhos

Tratando 429 no seu cliente

Boas práticas