Limites de requisições

As requisições à API são limitadas por chave de API, por grupo de endpoints:

Endpoints	Limite
GET /v1/products · GET /v1/balance · GET /v1/api-key · GET /v1/tasks/{token} · GET /v1/tasks/{token}/result · GET /v1/tasks/{token}/download	60 requisições / minuto por chave de API (120 / minuto por IP)
POST /v1/detect · POST /v1/detect/file	10 requisições / minuto por chave de API (30 / minuto por IP)
POST /v1/realtime/check/{series} · POST /v1/realtime/detect	Token bucket por chave de API: burst 60, recarga 1/s (≈60 / minuto sustentado); por conta: burst 120, recarga 2/s. A camada de IP permite 180 / minuto. Cada resposta inclui o cabeçalho X-RateLimit-Remaining.

Cabeçalhos de resposta

Os cabeçalhos que você recebe dependem de qual camada respondeu, e os três grupos não se comportam de forma idêntica:

Cabeçalho	Significado	Quando está presente
X-RateLimit-Remaining	Requisições (ou tokens) restantes na janela atual	Toda resposta nos três grupos
X-RateLimit-Limit	O teto que foi aplicado	Em toda resposta geral e de detecção, e em todo 429 da camada de IP. Nunca em uma resposta realtime — o realtime consome um bucket, então não há teto fixo a informar
Retry-After	Segundos a esperar antes de tentar novamente	Somente em um 429
X-RateLimit-Reset	Timestamp Unix de quando a janela é reiniciada	Somente em um 429 do grupo geral ou de detecção; nunca do realtime ou da camada de IP

X-RateLimit-Remaining é o único cabeçalho em que você pode confiar incondicionalmente, e o único que o realtime informa em caso de sucesso.

Quando você recebe um 429

Ao exceder um limite, a API retorna 429 com o cabeçalho Retry-After (respostas em tempo real também incluem o campo retry_after). Pause as requisições pelo número de segundos indicado e retome com backoff exponencial.

{
  "message": "Too many requests. Limit: 60/min."
}

Retry-After: 12
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0