Rate limits e throttling
Limites configurados por API key durante o acesso antecipado. Headers explícitos em toda resposta. Comportamento 429 documentado pro seu cliente fazer back-off limpo.
Headers em toda resposta
Toda resposta — sucesso ou 429 — inclui os headers padrão de rate limiting. Seu cliente pode lê-los pra fazer back-off proativo antes de tocar o limite.
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 37
X-RateLimit-Reset: 1715784823
Retry-After: 12| Header | Significado |
|---|---|
| X-RateLimit-Limit | Seu limite pra janela atual (requests permitidos na janela de rate limiting). |
| X-RateLimit-Remaining | Requests restantes na janela atual. Quando chega a 0, o próximo request vai devolver 429. |
| X-RateLimit-Reset | Timestamp em epoch UNIX (segundos) de quando a janela reseta e X-RateLimit-Remaining volta pra X-RateLimit-Limit. |
| Retry-After | Só presente em respostas 429. Segundos pra esperar antes de mandar o próximo request. |
Comportamento 429
Quando sua API key passa do limite configurado, devolvemos 429 Too Many Requests com o envelope de erro padrão e o header Retry-After indicando quantos segundos esperar.
O valor de error.code é sempre rate_limited. O message inclui o tempo de espera pra você também conseguir parsear do body se seu cliente não expõe o header.
{
"code": "rate_limit_exceeded",
"message": "Per-key rate exceeded. Retry after 12 seconds."
}Como o batch conta contra sua cota
Toda a API é batch: o mesmo endpoint valida 1 ou N itens. Cada item conta como uma validação — um lote de 100 itens consome 100 da sua cota mensal. Records conta por registro, não por campo: um registro com 6 campos consome 1. O rate limit por segundo aplica por request, não por item.
- Peças (emails · tax-ids · accounts · phones): até 1.000 itens por request.
- Records: até 500 itens por request.
- Um lote acima do teto retorna 400 batch_too_large; um vazio, 400 empty_batch. Para datasets maiores, você pagina no lado do cliente.
Estratégia recomendada
Quatro regras que cobrem quase todos os casos de integração com a API. Se seu workload é batch ou burst-heavy, menciona no formulário do waitlist pra gente ajustar os limites antes de emitir a key.
- Honra Retry-After ao pé da letra — não spamea com backoff fixo baixo quando recebe 429.
- Implementa exponential backoff com jitter pra respostas 5xx (não pra 429 — pra 429 usa Retry-After).
- Cacheia respostas idempotentes do lado do cliente. As validações são determinísticas: mesmo input → mesmo output, então cachear é seguro.
- Cacheie os resultados se valida contra a mesma base com frequência — um dado já validado não muda de formato. Some concorrência limitada no lado do cliente para não saturar o rate limit por segundo.
Limites durante o acesso antecipado
Os limites são configurados por API key. Durante o acesso antecipado a gente não publica um número global porque varia muito por caso de uso — um dashboard interno e um checkout público têm perfis de tráfego diferentes.
A gente não inventa um número genérico que depois não consegue sustentar. Pede o rate que precisa quando entrar na lista de espera e a gente seta antes de emitir a key.
Pra produção
Se você está planejando um deploy pra produção e precisa de cota maior ou garantias mais explícitas, entra na lista de espera mencionando o volume esperado.