# Limites de Taxa da API — Limitação por Conta e Cabeçalhos

> Os limites de taxa da v1 são aplicados por conta, não por endereço IP, e cada resposta inclui os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset para que você possa se autorregular antes de receber um erro 429.

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:

```json
{
  "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](/developers/guides/webhooks) 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.

---

Source: https://imagetotable.ai/pt/developers/guides/rate-limits