Limites de requisições da API

Os 5 níveis

Cada requisição passa por cinco portas. A primeira que negar vence.

Tetos diários por endpoint

Alguns endpoints têm limites mais apertados porque consomem tempo significativo de CPU ou GPU:

Limite de tamanho de arquivo

• 200 MB por arquivo para a API (contra 100 MB no site).
• Algumas ferramentas pesadas de IA têm limites internos menores — por exemplo, upscale-image tem teto de 20 MB para manter as execuções de GPU abaixo de 2 minutos.

Headers em cada resposta

Toda resposta bem-sucedida da API inclui os seguintes headers para que você possa acompanhar sua cota sem consultar /api/v1/limits:

X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 873
X-RateLimit-Reset-Day: 1775865600     # unix timestamp
X-RateLimit-Limit-Hour: 150
X-RateLimit-Remaining-Hour: 142
X-RateLimit-Limit-Endpoint: 50
X-RateLimit-Remaining-Endpoint: 38

O que acontece quando você atinge um limite

A API retorna 429 Too Many Requests com um header Retry-After (em segundos) e um header X-RateLimit-Reason indicando qual nível foi atingido:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Reason: cooldown

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded (cooldown). Retry after 1 seconds.",
    "details": { "reason": "cooldown", "retry_after": 1 }
  }
}

Valores possíveis de X-RateLimit-Reason: cooldown, burst, hourly, daily, endpoint:<name>, banned.

Escalada para ban

Abuso repetido aciona um ban temporário. Especificamente: 10 negações de rate limit em 1 hora a partir do mesmo IP → ban de 24 horas com HTTP 403 Forbidden e error.code: BANNED.

Se você acha que foi banido injustamente (por exemplo, porque compartilha um IP com muitos usuários), entre em contato em /contact e revisaremos.

Boas práticas para evitar throttling

• Aguarde pelo menos 1 segundo entre requisições consecutivas (ou use o header Retry-After nos 429).
• Use os endpoints batch para trabalho em massa: POST /api/v1/batch processa até 20 arquivos em uma única chamada HTTP (cada arquivo ainda conta na sua cota diária, mas você economiza idas e voltas).
• Observe os headers: quando X-RateLimit-Remaining-Day cair abaixo de 100, desacelere ou coloque seus resultados em cache.
• Inspecione seu uso a qualquer momento com GET /api/v1/limits — este endpoint NÃO conta na sua cota.
• Não tente novamente instantaneamente após um 429 — respeite Retry-After. Retentativas instantâneas podem acionar a escalada para ban.

Precisa de limites maiores?

Os limites atuais são padrões de MVP. Estamos observando o uso real e os ajustaremos conforme a demanda. Se você tem um caso de uso legítimo que precisa de cotas maiores, entre em contato via /contact.

Um futuro plano pago poderá oferecer cotas dedicadas, filas prioritárias e retenção de arquivos mais longa — mas o plano gratuito sempre continuará.