Skip to main content
A API aplica rate limit por API key com tiers configuráveis.

​
Limites por tier

TierRequests/minuto
free (default)100
pro1.000
enterprise10.000
Para mudar o tier de uma chave, contate o time da Voop.

​
Headers de resposta

Toda resposta inclui: 
X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset:     1714000060   (unix timestamp seconds)
Quando o limite é excedido, a resposta é 429 Too Many Requests com: 
Retry-After: 47   (seconds)

{
  "success": false,
  "error": {
    "code": "too_many_requests",
    "message": "Catalog API rate limit exceeded. Upgrade your tier for higher limits.",
    "retryAfter": 47
  }
}

​
Estratégia recomendada

1

Respeite Retry-After

Aguarde pelo menos o valor de Retry-After antes de retentar. Re-tentar imediatamente pode te colocar em backoff exponencial mais agressivo.
2

Backoff exponencial com jitter

Para erros 5xx ou 429 sem Retry-After, use backoff = min(2^attempt, 60s) ± jitter. Sem jitter, você cria thundering herd com outros clientes.
3

Monitore X-RateLimit-Remaining

Se cair abaixo de 10% do Limit, considere desacelerar proativamente.
4

Use bulk-upsert para reduzir consumo

1 chamada de bulk-upsert com 500 items = 1 request. 500 chamadas de upsert = 500 requests.

​
Bulk imports não consomem rate limit

Os endpoints POST /imports, POST /imports/:id/start, GET /imports/:id consomem o rate limit normal — mas o processamento dos itens dentro do JSONL não conta. Você pode importar 100k itens com 4 requests.
Para carga inicial grande, sempre use POST /imports (assíncrono via JSONL), não POST /items/bulk-upsert em loop.