Quase toda API pública impõe limites de uso. Se você faz um app que consome dados de terceiros, mais cedo ou mais tarde vai encontrar o rate limit. Entender como ele funciona evita bugs estranhos e bloqueios desnecessários.
O que é rate limit
É uma regra que restringe quantas requisições um cliente pode fazer em um intervalo de tempo. A API usa esse controle para proteger os servidores contra sobrecarga, evitar abusos e distribuir os recursos de forma justa entre os usuários.
Os limites variam muito. Podem valer por segundo, por minuto ou por dia, por chave de API, por usuário ou por endereço IP. Planos pagos costumam oferecer limites maiores. Os valores exatos estão sempre na documentação do serviço, e mudam com o tempo.
Se você ainda está começando a entender como esses serviços funcionam, o artigo O que é API e para que serve explica a base.
Como o limite se manifesta
Quando você passa do limite, a API costuma responder com o código de status 429. Muitas delas incluem cabeçalhos úteis na resposta:
- Um cabeçalho com o limite total permitido.
- Um cabeçalho com quantas requisições ainda restam.
- Um cabeçalho, como Retry-After, informando em quanto tempo você pode tentar de novo.
Os nomes exatos variam entre serviços, então confira na documentação.
Como lidar no seu código
Respeitar o tempo de espera
Se a resposta trouxer o tempo de espera, aguarde esse intervalo antes de tentar de novo. Insistir sem pausa só piora a situação e pode levar a um bloqueio mais longo.
Retentativas com espera crescente
Quando não há indicação, use retentativas com intervalo crescente, técnica conhecida como backoff exponencial. Você espera um pouco, tenta, e se falhar de novo espera mais. Defina um número máximo de tentativas e adicione um pequeno intervalo aleatório para evitar que vários clientes tentem ao mesmo tempo.
Reduzir o número de chamadas
- Guarde respostas em cache quando os dados mudam pouco.
- Agrupe pedidos quando a API aceita consultar vários itens de uma vez.
- Use filtros e paginação para buscar apenas o necessário.
- Prefira webhooks, quando existirem, em vez de consultar a API o tempo todo. O guia sobre webhooks explica a ideia.
Controlar o ritmo no cliente
Crie uma fila que libere as requisições em um ritmo compatível com o limite. Assim você não depende de receber erro para desacelerar.
Boas práticas
- Registre os erros 429 em log para saber quando e por que ocorrem.
- Mostre ao usuário uma mensagem clara, em vez de deixar o app travado.
- Nunca coloque a chave de API no código do navegador, porque outras pessoas podem usá-la e consumir o seu limite.
- Se o volume de uso cresce, avalie um plano maior em vez de tentar contornar a regra.
Tratar o rate limit como parte normal do funcionamento deixa o app mais estável e mais respeitoso com o serviço que ele consome.