Limites de taxa

Um limite de taxa protege a API por chave: as requisições são contadas por chave de API em uma janela fixa de um minuto. Requisições de leitura e de escrita têm limites separados (contadores independentes):

Operação	Método	Limite padrão
Leitura	GET	120 / minuto
Escrita	POST, PATCH, DELETE	60 / minuto

Os dois contêineres são independentes — ler intensivamente nunca consome seu orçamento de escrita, e vice-versa. Os cabeçalhos RateLimit-* de cada resposta refletem o contêiner correspondente ao método daquela requisição.

Cabeçalhos RateLimit

Toda resposta carrega o estado atual do limite, para que você possa limitar proativamente em vez de esperar por um 429:

RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 1751380920

• RateLimit-Limit — o limite máximo para a janela atual.
• RateLimit-Remaining — requisições restantes na janela atual.
• RateLimit-Reset — tempo Unix (segundos epoch) em que a janela é reiniciada e Remaining é recarregado.

Trate esses cabeçalhos como a fonte da verdade — o limite exato pode mudar ao longo do tempo, então leia-o a partir de RateLimit-Limit em vez de fixar 120 no código.

Quando você excede o limite

Assim que Remaining chega a 0, as requisições seguintes naquela janela recebem 429 Too Many Requests (rate_limit_error / too_many_requests) com um cabeçalho Retry-After:

HTTP/1.1 429 Too Many Requests
Retry-After: 2
RateLimit-Reset: 1751380920

• Respeite Retry-After — aguarde o número indicado de segundos e então tente novamente.
• Use recuo exponencial com jitter para limitações repetidas.
• Melhor ainda: observe RateLimit-Remaining e reduza a velocidade antes de chegar a 0.

Restrições de intervalo

Os endpoints de listagem de eventos exigem um intervalo from/to de no máximo 366 dias. Um intervalo maior é rejeitado com 422 validation_error (invalid_request).