Como lidar com rate limit na API Astrina

Cabeçalhos e campos de limite de taxa a verificar primeiro

Comece pela própria resposta. Se uma requisição for rejeitada, os cabeçalhos e os metadados normalmente dizem mais do que o texto do erro.

Procure campos que indiquem o tempo de redefinição, a cota restante e a categoria do limite. Se a Astrina retornar dados de classificação, mantenha-os no log também, porque o mesmo endpoint pode se comportar de forma diferente para tipos de requisição distintos. Ao solucionar limites de taxa da API Astrina, isso é especialmente importante, porque pequenas diferenças nos cabeçalhos podem explicar por que uma chamada funciona e a seguinte falha. Em outras palavras, saber como lidar com rate limit na API Astrina começa por ler esses sinais com atenção.

Um hábito simples economiza tempo depois: registre o timestamp exato da requisição, não apenas o erro. Um valor de redefinição que parece “errado” muitas vezes é só uma divergência de relógio. Já vi isso mais de uma vez.

Se o seu cliente já armazena códigos de status, adicione os cabeçalhos relevantes ao lado deles. Isso facilita perceber um padrão quando o teto é atingido às 09:00 e de novo às 09:03. Dois números contam a história mais rápido do que um parágrafo de suposições. Para isso, documente também os headers de limite de taxa API Astrina que vierem na resposta.

No astrina, esse é o tipo de detalhe que ajuda uma integração a sair do achismo e chegar às evidências. O objetivo é simples: saber se você está bloqueado, quanto tempo dura o bloqueio e qual tipo de requisição o disparou.

Distinguir limites por usuário, por chave e por endpoint

Nem todo controle de taxa é igual. Um único usuário pode atingir um limite baseado em usuário enquanto a mesma chave ainda funciona para outra conta, e um teto específico de endpoint pode falhar em um caminho enquanto o restante da API continua aberto.

Essa distinção importa porque a correção muda. Se uma credencial se esgotou, talvez seja apropriado alternar as requisições para outra chave. Se um endpoint foi limitado, espalhar o tráfego por caminhos não relacionados não ajudará. Se a conta inteira está restringida, o padrão é mais amplo do que um único token.

Verifique qual requisição falha primeiro. Depois repita a mesma chamada com um usuário diferente, uma chave diferente ou um caminho diferente, alterando uma variável por vez. Três testes, não dez, muitas vezes revelam o limite.

Pense nisso como um mapa com três trancas. A tranca de uma porta não significa que o prédio inteiro está fechado. Pode ser apenas a porta que você escolheu.

Uma pista prática é a repetição. Se as requisições para `/search` falham enquanto `/status` ainda funciona, isso aponta para um limite de endpoint. Se ambas falham apenas para uma credencial, o limite provavelmente está vinculado àquela identidade.

O que uma resposta “rate limited” significa na prática

Uma resposta “rate limited” significa que o servidor decidiu que a requisição atual não é permitida agora. Isso não quer dizer automaticamente que a conta está quebrada, que a chave é inválida ou que o sistema está fora do ar.

Algumas requisições ainda podem funcionar em outros lugares. Um endpoint com alto volume de leitura pode ser bloqueado enquanto um endpoint com menor volume continua respondendo normalmente. Por isso o cliente não deve presumir que a sessão inteira morreu após uma única rejeição.

Registre o contexto completo de cada falha: endpoint, ID da credencial, horário da requisição, código de status e qualquer request ID retornado pela API. Sem esses cinco elementos, o suporte precisa reconstruir a cena a partir de fragmentos. Saber o que fazer quando a API retorna rate limited depende exatamente desse contexto.

Um erro comum do lado do cliente é tratar toda rejeição como o mesmo evento. Não é. Um limite de taxa é temporário, enquanto um erro de autenticação geralmente não é. Misturar os dois leva a novas tentativas ruins e a interrupções mais longas.

No site que você acompanha, vale a mesma regra: uma requisição bloqueada deve ser rotulada como bloqueada, e não apenas como “falha”. Esse pequeno rótulo mantém os painéis honestos.

Comportamento imediato do cliente após o throttling

Depois de um throttle, pare de enviar a mesma requisição em loop apertado. Um frontend deve pausar essa ação, um job de backend deve mover o item para uma fila de retry e uma integração deve segurar a próxima chamada até passar o tempo de redefinição ou a janela de backoff.

Em fluxos interativos, mostre uma mensagem curta e uma opção de tentar novamente. Para jobs, prefira uma fila com um campo de atraso claro. Para scripts, saia de forma limpa e deixe o agendador tentar de novo mais tarde. Três ambientes, três reações.

Não fique martelando o mesmo endpoint. Se 20 requisições já foram bloqueadas, a 21ª não será mais convincente.

Preserve o payload original. Se a requisição puder ser reenviada com segurança, armazene dados suficientes para reconstruí-la exatamente quando a espera terminar. Se a requisição cria estado, garanta que o servidor consiga lidar com duplicatas, porque uma nova tentativa atrasada pode chegar depois que a primeira tentativa eventualmente tiver sucesso.

Esse também é o momento de separar a latência percebida pelo usuário do comportamento do sistema. Um spinner pode esperar 5 segundos; um executor de jobs pode esperar 5 minutos. O cliente precisa saber qual é qual.

Backoff e tempo de retry para rajadas curtas

Rajadas curtas exigem disciplina. Comece com um atraso, depois aumente a espera após cada nova falha usando backoff exponencial e adicione jitter se o seu cliente suportar.

O jitter importa porque retries sincronizados fazem barulho. Se 50 workers acordarem exatamente no mesmo segundo, eles podem criar uma segunda onda de pressão. É assim que um throttle curto vira um longo.

Use um número máximo de tentativas. Cinco tentativas podem ser suficientes para uma rajada breve; cinquenta geralmente sinalizam que o cliente está ignorando o limite em vez de respeitá-lo.

Um padrão simples funciona bem: espere 1 segundo, depois 2, depois 4, depois 8, adicionando um pequeno offset aleatório. Os números exatos podem variar conforme o sistema, mas a forma do comportamento deve permanecer calma e previsível.

Se a API publicar um horário de redefinição, prefira isso em vez de suposições. Se não publicar, o backoff é mais seguro do que consultas agressivas em loop. Uma requisição extra pode sair cara quando o teto já está à vista.

Separar throttling temporário de erros de autenticação ou permissão

Limites de taxa e erros de acesso são parentes, não gêmeos. Um token ruim normalmente falha o tempo todo. Um throttle falha apenas sob pressão.

Teste a mesma credencial em um endpoint de baixo custo. Se essa requisição funcionar, o token provavelmente é válido e o problema é volume, não autenticação. Se falhar com o mesmo padrão, o problema pode ser permissão, expiração ou uma chave revogada.

Observe o código de status e o corpo da resposta juntos. Uma resposta de limite costuma ter uma forma diferente da resposta de credenciais inválidas, mesmo quando ambas chegam como erros da classe 4xx. O corpo pode nomear o tipo de limite, enquanto um problema de permissão pode mencionar escopo ou acesso negado.

Não recrie a credencial na primeira rejeição. Isso pode desperdiçar horas. Confirme se a falha está ligada à carga, à identidade ou a uma concessão ausente.

Um passo de diagnóstico claro é comparar uma chamada bem-sucedida do início do dia com a que falhou. Mesma chave, mesmo endpoint, resultado diferente. Esse contraste geralmente reduz o problema rapidamente.

Monitorar eventos de limite de taxa em logs e alertas

Os logs devem responder a quatro perguntas: com que frequência, onde, quem e por quanto tempo. A frequência mostra a escala. O endpoint afetado mostra o ponto quente. O request ID liga o suporte à chamada exata. O tempo até a recuperação mostra se o cliente esperou o suficiente.

Dispare alertas para throttles repetidos, não para um único pico isolado. Uma única sequência de falhas pode ser um usuário clicando duas vezes. Dez em dois minutos já é um padrão que merece atenção.

Mantenha o request ID no payload do alerta. Adicione o usuário, a chave ou o nome do job, se o seu sistema tiver esses dados. Isso torna o alerta útil tanto para engenharia quanto para suporte.

Uma linha de log limpa pode incluir o endpoint, o status, a categoria do limite, o horário de redefinição e a contagem de retries. Cinco campos bastam para a maioria das investigações. Mais é aceitável, mas menos costuma virar uma busca por pistas.

Se você estiver comparando tráfego entre produtos, astrina pode ajudar a manter a mesma atividade visível em um só lugar. Isso importa quando um painel mostra uma subida suave e outro mostra um pico acentuado.

Quando escalar para o suporte da Astrina

Escalone quando o tráfego normal ainda estiver sendo limitado depois que você verificar o comportamento do cliente, a combinação de endpoints e o tempo de retry. Um limite que dispara no uso rotineiro não é algo para ficar adivinhando por muito tempo.

Leve evidências. Inclua timestamps, request IDs, o nome do endpoint, a referência da credencial ou da conta e o comportamento observado de redefinição. Um ticket de suporte com esses cinco itens é muito mais fácil de agir do que “continua falhando”.

Também vale escalar se o comportamento do limite parecer inconsistente. Se a mesma requisição é permitida às 10:01 e bloqueada às 10:02 sem mudança relevante no volume, isso merece uma análise mais atenta.

Há mais um caso que chama atenção: se sua integração for pequena, mas compartilhada por muitas equipes, um pico aparentemente modesto pode parecer um evento de sistema maior. Nesse cenário, o suporte pode confirmar se o teto no nível da conta está sendo atingido ou se algum job está se comportando mal.

Se o seu caso de uso envolve várias propriedades, cada site de cliente em um único painel pode deixar a investigação mais clara, porque o mesmo evento de limite pode ser rastreado entre contas sem precisar alternar entre ferramentas.

Mantenha a conversa específica. “Batemos no teto três vezes entre 14:10 e 14:18 em `/reports` com a chave X” é acionável. “A API está lenta” não é. A primeira frase aponta para um limite. A segunda aponta para uma sensação.