429 Too Many Requests: limites de taxa, Retry-After e alarmes falsos

O que um 429 significa e o que vem junto

O 429 é definido na RFC 6585 como o status para limitação de taxa: o cliente enviou requisições demais em um dado intervalo de tempo. A especificação deixa duas coisas deliberadamente em aberto: como o servidor identifica o cliente e como as requisições são contadas. É por isso que os limites de taxa variam tanto entre serviços.

Na prática, os servidores contam por endereço IP, por chave de API, por sessão, por conta ou por alguma combinação disso, e usam janelas fixas, janelas deslizantes ou baldes de tokens. Duas taxas idênticas de requisição podem, portanto, passar em um endpoint e ser bloqueadas em outro do mesmo site.

A resposta traz os sinais de que você precisa:

• Retry-After é o padronizado. A RFC 9110 permite um número de segundos ou uma data HTTP, e um cliente bem-comportado espera esse tempo antes de tentar de novo.
• Cabeçalhos de limite de taxa como RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset, ou as variantes mais antigas com X-RateLimit-, expõem o orçamento e quando ele é reiniciado. São convenções, não parte da RFC 9110, então consulte a documentação da API para saber os nomes exatos.
• O corpo deve explicar o limite em termos legíveis por humanos. Muitas APIs dizem qual cota foi excedida, o que poupa bastante adivinhação.

Um 429 não é cacheável por padrão, então intermediários não devem continuar servindo essa resposta depois que a janela é reiniciada.

Limite de taxa ou queda de verdade?

Os dois são confundidos o tempo todo, porque ambos aparecem como requisições que falham. Os testes que os distinguem são rápidos:

• O próprio código. Um limite de taxa responde 429. Um servidor sobrecarregado ou em modo de manutenção responde 503. Os dois podem trazer Retry-After, e é por isso que as pessoas os misturam, mas eles significam coisas diferentes: o 429 diz "você especificamente está enviando demais", o 503 diz "o serviço como um todo não consegue aceitar trabalho agora". Veja o guia do 503 para esse lado.
• Tempo de resposta. Limites de taxa rejeitam rápido, normalmente em milissegundos, porque a decisão é tomada antes de qualquer trabalho real. A sobrecarga responde devagar ou estoura o tempo.
• Quem é afetado. Um limite de taxa atinge uma identidade de cliente. Teste de outro endereço IP ou com outra chave de API: se funcionar enquanto o cliente restringido continua falhando, é um limite, não uma queda.
• O padrão ao longo do tempo. A limitação de taxa é periódica e se resolve sozinha. As falhas se agrupam, param exatamente quando a janela é reiniciada, e voltam. Uma queda não retoma educadamente em horário marcado.
• Correlação com o seu próprio volume. Se as falhas começaram quando você aumentou a frequência de uma verificação, acrescentou workers paralelos ou disparou um lote, a causa está do seu lado da conexão.

Por que o monitoramento pode disparar um 429 contra si mesmo

Monitoramento é uma requisição repetida, vinda de um conjunto pequeno de endereços, para a mesma URL, o que é bem parecido com o formato que os limitadores de taxa foram feitos para pegar. Um intervalo de verificação muito curto piora isso, porque verificações a cada minuto multiplicadas por muitas URLs monitoradas somam rápido contra um orçamento por IP. Rodar uma verificação de muitas localizações ao mesmo tempo também: a origem vê uma rajada em vez de um fluxo constante, e os limites de rajada disparam primeiro.

A escolha da URL também importa. Páginas de busca, endpoints de API e qualquer coisa que escreva costumam ser limitados com mais rigor do que uma página inicial estática. E se o monitoramento e a aplicação compartilham uma chave de API, os dois competem por uma cota só. O resultado é um monitor relatando que o site está falhando enquanto o site está perfeitamente saudável, e um limitador de taxa fazendo o trabalho dele corretamente.

Como corrigir um 429

1. Leia os cabeçalhos da resposta antes de mudar qualquer coisa:

   curl -sS -o /dev/null -D - https://example.com/api/items

   Retry-After e os cabeçalhos de limite de taxa dizem qual é o orçamento real, o que é melhor do que adivinhar intervalos.
2. Respeite o Retry-After. Tentar de novo na hora estende o bloqueio em muitas implementações. Espere o tempo indicado.
3. Recue exponencialmente, com jitter, no código do cliente, para que clientes concorrentes não sincronizem e tentem de novo todos juntos.
4. Reduza a taxa de requisições. No monitoramento, mova um endpoint verificado para um intervalo maior, ou escalone as verificações para que várias localizações não disparem no mesmo segundo.
5. Monitore uma URL barata e representativa. Um endpoint de saúde leve ou a página inicial diz que o site está no ar sem gastar a cota de que você precisa para o tráfego real.
6. Isente o cliente de monitoramento no limitador. Coloque os endereços dos pontos de verificação em uma lista de permissões, ou dê ao monitoramento uma chave de API própria com orçamento próprio, para que ele nunca compita com o tráfego de produção.
7. Se o limitador é seu, confira se o limite está certo. Pergunte se o orçamento corresponde ao uso real, se ele é por IP quando deveria ser por conta, e se proxies compartilhados ou NAT corporativo estão colocando muitos usuários atrás de um endereço só.

Observar 429 sem causá-los

Limites de taxa normalmente aparecem primeiro para os clientes mais ativos, o que significa que clientes pagantes e integrações batem neles antes de qualquer pessoa da sua equipe. Uma verificação HTTP programada que exige o código de status esperado mostra um 429 como um evento distinto e datado, em vez de relatos esparsos de que "a API está instável", e o horário diz se o limite é periódico ou permanente. Escolha o intervalo com cuidado: frequente o bastante para notar problemas rápido, suave o bastante para que a verificação nunca seja a coisa que dispara o limite. A família mais ampla de recusas, incluindo 401 e 403, é tratada na visão geral dos 4xx.