Limites de Taxa
Os limites de taxa são aplicados por conta autenticada, com base na sua chave de API — não por endereço IP. Isso significa que o mesmo cliente acessando a API de várias máquinas/IPs ainda compartilha um único limite, e clientes diferentes que compartilham um IP de saída (atrás de um proxy corporativo, por exemplo) não afetam uns aos outros.
Limites por categoria de endpoint
| Categoria | Limite | Endpoints |
|---|---|---|
| Upload / processamento | 30 por minuto | POST /documents, POST /batches/{batch_name}/process, POST /documents/{document_id}/bbox, PUT /batches/{batch_name}/webhook |
| Consulta de status / resultados | 120 por minuto | GET /documents/{document_id}, GET /batches, GET /batches/{batch_name}, GET /batches/{batch_name}/results, GET /documents/{document_id}/bbox, GET /documents/{document_id}/image, GET /account, GET /account/usage, endpoints de modelo/campo |
| Exportação | 10 por minuto, 60 por hora | GET /batches/{batch_name}/export |
Estes são os padrões atuais e podem ser ajustados ao longo do tempo; os cabeçalhos de resposta descritos abaixo sempre refletem o que está realmente em vigor para o endpoint que você chamou, portanto, baseie-se nos cabeçalhos em vez de codificar esses números.
Cabeçalhos de resposta
Toda resposta com limite de taxa — bem-sucedida ou não — inclui três cabeçalhos que descrevem sua situação:
| Cabeçalho | Significado |
|---|---|
X-RateLimit-Limit | Número total de requisições permitidas na janela atual. |
X-RateLimit-Remaining | Requisições restantes na janela atual. |
X-RateLimit-Reset | Quando a janela atual é reiniciada. |
Verifique X-RateLimit-Remaining proativamente em um loop de polling e reduza a velocidade antes de chegar a zero, em vez de esperar para reagir a um 429.
Quando você excede um limite
Exceder um limite retorna HTTP 429 com a estrutura de erro padrão da v1:
{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Muitas requisições. Reduza a velocidade e tente novamente após a reinicialização da janela.",
"doc_url": "https://imagetotable.ai/developers/guides/errors#rate_limit_exceeded"
}
}Se você estiver fazendo polling do status do lote, prefira registrar um webhook em vez de um loop de polling intenso — isso elimina o risco de atingir o limite de polling de status completamente nesse caso de uso.