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.
Trate uma resposta 429 sem perder a requisição
Um código de status 429 não é o mesmo tipo de falha que um 400 ou um 404. Ele significa que a requisição estava bem formada e teria funcionado, mas a sua cota do período atual se esgotou.
Como é a resposta
HTTP/1.1 429 Too Many Requests
X-Quota-Limit: 2500
X-Quota-Used: 2500
X-Quota-Free-Remaining: 0
X-Credits-Remaining: 0.00
X-Quota-Reset: 2026-09-22T00:00:00Z
{
"status": "error",
"error": {"code": "quota_exceeded", "message": "Daily quota exceeded"}
}Não descarte a requisição
O erro mais comum é tratar um 429 da mesma forma que um 400, registrando-o como falha e seguindo em frente. A consulta que o usuário ou o seu script queria continua perfeitamente válida, só precisa ser executada mais tarde ou com outras credenciais. Coloque o payload original da requisição em uma fila de novas tentativas em vez de descartá-lo.
Lendo o horário de redefinição
O cabeçalho X-Quota-Reset na resposta 429 informa exatamente quando a cota diária é redefinida. Um job em segundo plano pode aguardar até esse horário e então retomar a fila, em vez de consultar repetidamente ou adivinhar um intervalo fixo entre tentativas.
Um segundo cenário para o qual vale se preparar
Um 429 nem sempre significa que toda a cota do dia acabou. Se X-Key-IPs-Used atingiu X-Key-IPs-Limit, uma chave pode ser temporariamente recusada a partir de um novo endereço de origem, mesmo que requisições dos seus endereços habituais ainda funcionem. Verificar qual cabeçalho realmente explica o 429, esgotamento da cota ou limite de vagas de IP, muda a solução: esperar a redefinição em um caso e reduzir o número de máquinas diferentes que usam a mesma chave no outro.
Duas formas de passar do limite agora mesmo
Se esperar não for aceitável, há duas opções imediatas: recarregar crédito pré-pago a € 0,0001 por requisição ou passar para uma chave Unlimited a € 50 por mês, se isso for um padrão recorrente e não um pico pontual. Ambas removem o teto diário que provocou o 429 em primeiro lugar.
Separando os limites da chave dos limites da rede
Como a cota gratuita é compartilhada por toda uma faixa /24 no IPv4 ou /48 no IPv6, um 429 pode acontecer por causa do tráfego de outros endereços da mesma rede, e não apenas do uso da sua própria chave. Verifique X-Quota-Network-Used junto com X-Quota-Used para distinguir as duas situações antes de decidir se um upgrade de chave vai realmente resolver algo.
Um erro que vale a pena evitar
Repetir imediatamente uma requisição que falhou, em um loop apertado, assim que um 429 chega, só acrescenta mais chamadas malsucedidas a uma cota que já está esgotada, sem aproximar você de uma requisição que funcione. Aguarde até o horário de redefinição indicado no cabeçalho, ou um intervalo fixo razoável se o trecho de código não ler cabeçalhos, em vez de bombardear o endpoint de novo logo em seguida.
Tratar um 429 como "tente novamente em breve", e não como "isto falhou", mantém uma fila andando normalmente durante a redefinição da cota, em vez de perder trabalho. Os detalhes sobre os formatos de erro da API estão na página de erros, e as opções de cota atuais estão na página de preços.