Monitore o uso da sua chave antes de atingir um limite
Acompanhar seus cabeçalhos de cota ao longo do caminho mostra quando um limite está se aproximando, bem antes de uma requisição ser realmente rejeitada.
Leia corretamente os cabeçalhos X-Quota-Used e X-Quota-Limit
Cada resposta da API, bem-sucedida ou não, traz um conjunto de cabeçalhos que descreve exatamente a sua situação em relação à sua cota. Lê-los corretamente significa entender o que cada um conta.
O par principal
X-Quota-Limit é o tamanho da sua cota atual, seja a cota gratuita diária ou o limite efetivo com um pacote Unlimited. X-Quota-Used é quantas requisições já foram contabilizadas nessa cota no período atual. Subtrair um do outro manualmente é desnecessário, já que X-Quota-Free-Remaining já faz isso por você.
HTTP/1.1 200 OK
X-Quota-Limit: 2500
X-Quota-Used: 1840
X-Quota-Free-Remaining: 660
X-Quota-Network-Used: 1840
X-Credits-Remaining: 0.00
X-Key-IPs-Used: 1
X-Key-IPs-Limit: 3
X-Quota-Reset: 2026-09-22T00:00:00ZUso da chave versus uso da rede
X-Quota-Used reflete o uso ligado à sua chave, enquanto X-Quota-Network-Used reflete o uso da rede ao redor, já que a cota gratuita é compartilhada entre todos os endereços IPv4 do mesmo /24 e todos os endereços IPv6 do mesmo /48, com ou sem chave. Se uma chave é chamada a partir de vários servidores atrás do mesmo bloco de endereços, o número da rede vai subir mais rápido do que qualquer servidor isolado esperaria com base no próprio tráfego.
O par de vagas de IP
X-Key-IPs-Used e X-Key-IPs-Limit descrevem algo totalmente diferente: quantos endereços de origem distintos usaram essa chave específica recentemente, em relação ao limite móvel de dois ou três endereços permitidos por chave. Uma chave chamada a partir de um único servidor vai mostrar um 1 estável aqui. Uma chave compartilhada entre vários servidores sem relação entre si, ou copiada em um script que acaba rodando em muitas máquinas, vai subir em direção ao limite, o que vale acompanhar separadamente da sua cota de requisições, já que isso pode bloquear uma chave mesmo quando ainda restam muitas requisições gratuitas.
Créditos e horário de reinicialização
X-Credits-Remaining mostra o seu saldo pré-pago depois que você ultrapassou a cota gratuita e está consumindo crédito a € 0,0001 por requisição. X-Quota-Reset informa exatamente quando a cota diária atual será reiniciada, o que é mais confiável do que presumir um horário fixo com base no seu próprio relógio.
O que construir com base nesses cabeçalhos
Um painel, um alerta ou apenas uma linha de log que leia esses cabeçalhos após cada chamada oferece uma visão em tempo real do uso sem precisar de uma chamada de relatório separada, já que os números chegam na resposta da requisição que você já fez. Lê-los não custa nada a mais, já que eles vêm junto com cada requisição que você já estava enviando, tenha ela sido bem-sucedida ou retornado um erro.
Um erro que vale a pena evitar
Ler esses cabeçalhos só quando algo dá errado significa descobrir um problema de cota no mesmo momento que os seus usuários. Registre pelo menos X-Quota-Free-Remaining e X-Credits-Remaining em intervalos regulares, ou após cada chamada em uma integração de baixo tráfego, para que uma subida lenta em direção ao limite apareça como uma tendência em um painel, e não como um lote repentino de respostas 429.
Ler os cabeçalhos de cota em cada resposta, em vez de esperar um 429 para perceber um problema, é a diferença entre uma desaceleração tranquila e uma desaceleração inesperada. A lista completa de cabeçalhos está documentada na página de limites de taxa.