Rate limiting

A API pública aplica limite de 600 requisições por minuto por chave de API, em janela fixa: o contador zera no início de cada minuto. O limite vale para todos os métodos, somados.

Headers de resposta

Toda resposta autenticada informa o estado da sua janela atual:

Header	Exemplo	Descrição
X-RateLimit-Limit	600	Limite de requisições da janela.
X-RateLimit-Remaining	597	Requisições restantes na janela atual.
X-RateLimit-Reset	1753272060	Unix time (segundos) em que a janela reinicia.
Retry-After	27	Só em 429: segundos até poder re-tentar.

Resposta ao exceder

Ao estourar o limite, a API responde 429 Too Many Requests com o envelope de erro padrão:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1753272060
Retry-After: 27

{
  "message": "Limite de requisições excedido",
  "code": "RATE_LIMITED"
}

Aguarde os segundos indicados em Retry-After (ou até o instante de X-RateLimit-Reset) antes da próxima requisição. Como a janela é fixa, re-tentar antes só desperdiça chamadas — a resposta continuará 429 até a virada do minuto.

Boas práticas

• Monitore X-RateLimit-Remaining e reduza o ritmo antes de chegar a zero, em vez de reagir ao 429.
• Re-tente com backoff respeitando Retry-After — nunca em loop imediato.
• Use X-Idempotency-Key nas mutações: o retry pós-429 é seguro e não duplica a operação.
• Prefira filtros de listagem e per_page=100 a varreduras página a página — menos requisições, mesma informação (Paginação e filtros).
• Distribua cargas em lote (importações, sincronizações) ao longo do tempo em vez de rajadas no início do minuto.