Rate limits

Aplicamos rate limit por API key, em uma janela móvel de 1 hora. Os uploads diretos ao R2 com URLs pré-assinadas NÃO contam contra esse limite — só as chamadas aos endpoints /v1/* contam.

Limites por plano

Quando você excede o limite

HTTP/1.1 429 Too Many Requests
Retry-After: 1847
X-RateLimit-Limit: 100
X-RateLimit-Reset: 1780201234

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded (100 requests/hour). Retry in 1847s.",
    "retry_after_seconds": 1847
  }
}

Headers de resposta

Em cada resposta 429 incluímos esses headers para você implementar backoff corretamente:

• Retry-After — segundos até a janela ser resetada
• X-RateLimit-Limit — seu limite atual por hora
• X-RateLimit-Reset — timestamp Unix de quando reseta

Boas práticas

• Faça cache da resposta de GET /v1/me — não chame antes de cada operação.
• Para upload em massa, paralelize com um semáforo (ex.: 10 concorrentes).
• Se você precisar de >10.000 requests/hora sustentado, fale conosco: armamos acordo enterprise.