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.
{
"error": {
"code": "rate_limited",
"message": "Quota exceeded. Retry after 12 seconds.",
"request_id": "req_a1b2c3d4e5f6g7"
}
}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.
- Batch no cliente se precisar validar muitos records — durante o acesso antecipado não tem endpoint batch em /v1/. Concorrência limitada + cache resolve quase todos os casos.
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.