Limites de pedidos

#O limite

Cada chave pode fazer 120 chamadas por minuto. A API REST e o servidor MCP contam na mesma janela, por isso um assistente de IA e uma sincronização que partilham uma chave partilham o seu limite; dê uma chave a cada um.

Uma sincronização que lê 500 participantes por página lê 60 000 participantes dentro do limite, por isso uma integração bem feita raramente o atinge. Um ciclo que pede a mesma coisa vezes sem conta atinge-o em menos de um minuto, e é para isso que ele existe.

#Em que ponto está

Cada resposta, incluindo as recusas, indica o limite de duas formas: os cabeçalhos RateLimit do IETF e os cabeçalhos X-RateLimit-* que a maioria das bibliotecas cliente lê.

HTTP/1.1 200 OK
RateLimit-Policy: "default";q=120;w=60
RateLimit: "default";r=117;t=42
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 42

r (remaining) é o número de chamadas que restam nesta janela e t os segundos até começar uma nova janela.

#Quando ultrapassa o limite

A chamada é recusada com 429 Too Many Requests, um cabeçalho Retry-After em segundos e um problema com "code": "rateLimited". Nada foi feito: espere e envie-a de novo. Uma chamada recusada conta na atividade das chaves, para que possa ver quando aconteceu.

HTTP/1.1 429 Too Many Requests
Retry-After: 18
Content-Type: application/problem+json

{ "status": 429, "code": "rateLimited", "detail": "This key made more than 120 calls in a minute. Try again in 18 seconds; the RateLimit header says what is left." }

#Ficar bem dentro do limite

• Peça páginas grandes: limit=500 não é problema.
• Sincronize com updatedSince em vez de ler tudo de cada vez (Paginação e sincronização).
• Use webhooks em vez de consultas periódicas para o que acabou de acontecer.
• Envie If-None-Match com o ETag que tem: um 304 é rápido, embora continue a contar.
• Faça uma pausa quando o r de RateLimit estiver baixo, em vez de esperar pela recusa.

A janela é contada por servidor, por isso num dia movimentado uma chave pode, de vez em quando, obter um pouco mais do que o limite. Não conte com isso: trate os cabeçalhos como a verdade.