Limites de requisições

Os limites existem para manter a API rápida e estável para todas as agências. Eles foram pensados para o uso normal de um site ou de uma integração, que consulta os dados em rajadas: não é preciso contar as requisições uma a uma.

Os limites

Limite	Valor	Vale para
Por token	1.000 requisições por minuto	Cada token, somando todos os endpoints de leitura.
Por agência	3.000 requisições por minuto	Todos os tokens da agência somados.

• Todos os endpoints atuais da API são de leitura e usam o limite acima. Operações que alterem dados, caso venham a existir, terão um limite próprio e menor.
• O limite por agência impede que criar mais tokens multiplique a capacidade: dois tokens da mesma agência dividem os mesmos 3.000 por minuto.
• Cada token tem o seu próprio contador. O consumo de um token não afeta o de outro, desde que a soma da agência fique dentro do limite.
• A contagem é feita em janelas de um minuto e volta a zero quando a janela termina.

Para ter uma ideia: 1.000 por minuto são cerca de 16 requisições por segundo, em média. Uma rajada de 150 requisições em poucos segundos, como a de 30 visitantes chegando juntos ao site e fazendo 5 chamadas cada, usa uma pequena parte do limite e não é bloqueada.

Cabeçalhos de consumo

Toda resposta da API informa o seu consumo:

Cabeçalho	Descrição
X-RateLimit-Limit	O limite por minuto que vale para a sua requisição.
X-RateLimit-Remaining	Quantas requisições ainda restam na janela atual.

Quando dois limites se aplicam (o do token e o da agência), os cabeçalhos mostram o que tem menos espaço sobrando. Assim, X-RateLimit-Remaining é sempre uma estimativa segura de quantas requisições você ainda pode fazer.

Acompanhe X-RateLimit-Remaining em processos longos, como a leitura de todas as páginas de uma lista, e diminua o ritmo antes que ele chegue a zero.

Quando o limite é excedido

Se você passar do limite, a API responde 429:

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790000023
Content-Type: application/json

{"message":"Too Many Attempts."}

Além dos cabeçalhos de consumo, a resposta 429 traz:

Cabeçalho	Descrição
Retry-After	Quantos segundos esperar antes de tentar de novo.
X-RateLimit-Reset	O momento em que a janela reabre, como um timestamp Unix (segundos desde 1970).

Respeite esse tempo: novas requisições feitas antes dele também recebem 429. Se a sua integração recebe 429 com frequência, aumente a pausa a cada nova tentativa (backoff exponencial) em vez de repetir a chamada em um laço rápido.

Como ficar dentro dos limites

• Chame a API pelo servidor do seu site e guarde as respostas por até 30 minutos. Um site com muitas visitas faz poucas chamadas à API e continua rápido. Veja Boas práticas.
• Use a validação por ETag. Uma requisição com If-None-Match que não mudou recebe 304 e não traz o conteúdo. Veja Boas práticas.
• Peça páginas grandes. Use per_page=50 para ler uma lista inteira com menos requisições.
• Use filtros para trazer só o que precisa. Veja Filtros.

Precisa de mais?

Se a sua integração tem uma necessidade real de mais de 1.000 requisições por minuto, fale com o suporte da Avoei e explique o caso de uso.