429 Solicitações em excesso: o que significa e como lidar com isso

Uma API retorna 429 Too Many Requests quando seu aplicativo enviou mais solicitações do que a API permite em um período de tempo. A solicitação em si está boa. Você o enviou com muita frequência, então a API o recusou. Se você esperar e enviá-lo novamente, ele geralmente terá êxito. A resposta geralmente inclui um Retry-After cabeçalho que informa quanto tempo esperar. Para obter mais informações, consulte RFC 6585, seção 4.

Cada API implementa limites de requisição de forma diferente. O código de status, os cabeçalhos e o corpo do erro variam, de modo que o código que manipula uma API corretamente pode manipular incorretamente a próxima API.

API Status Como saber quanto tempo esperar Cuidado com
GitHub 403 ou 429 retry-after se estiver presente, caso contrário x-ratelimit-reset (segundos de época UTC) quando x-ratelimit-remaining for 0, caso contrário, pelo menos 1 minuto Um 403 pode ser um limite de taxa ou uma permissão ausente. Leia os cabeçalhos para diferenciá-los.
OpenAI 429 retry-after Alguns erros 429, como credit_balance_exhausted, significam que tentar novamente não vai ajudar. Verifique error.code.
Antrópico 429 retry-after Um limite de gastos 429 não tem retry-after e continua falhando até que o acesso seja retomado. Uma API sobrecarregada retorna 529, não 429.
Microsoft Graph 429 Retry-After (segundos) Os limites diferem por serviço, por exemplo, SharePoint e Outlook.

Como lidar com um 429

  1. Decida se tentará novamente. Se o erro indicar que sua cota, créditos ou limite de gastos se esgotaram, tentar novamente não ajudará. Diga ao usuário e alerte a si mesmo.
  2. Aguarde o tempo que a API solicitar. Se a resposta tiver Retry-After, aguarde esse tempo. É um número de segundos ou uma data HTTP. Se a API usar cabeçalhos de limite de taxa, como GitHubx-ratelimit-reset, aguarde até o tempo de redefinição.
  3. Caso contrário, recue. Sem uma dica da API, tente novamente com backoff exponencial e jitter aleatório e pare após algumas tentativas.
  4. Diga ao usuário o que está acontecendo. "Ocupado, tentando novamente em 5 segundos" bate um spinner que nunca termina.
  5. Desacelere antes do próximo 429. Se a API enviar cabeçalhos de limite de taxa, use a contagem restante para ajustar o ritmo das suas solicitações.
async function fetchWithRetry(url, options, attempts = 3) {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch(url, options);
    if (response.status !== 429 || attempt === attempts) {
      return response;
    }
    const retryAfter = response.headers.get('retry-after');
    const waitMs = retryAfter
      ? (isNaN(retryAfter) ? new Date(retryAfter) - Date.now() : retryAfter * 1000)
      : 2 ** attempt * 1000 + Math.random() * 1000;
    await new Promise(resolve => setTimeout(resolve, Math.max(waitMs, 0)));
  }
}

Muitos SDKs tentam novamente em respostas 429 para você. Por exemplo, o SDK de Python do OpenAI tenta novamente 2 vezes por padrão e o manipulador de resiliência padrão .NET tenta 3 vezes e honraRetry-After. Quando o SDK esgota as tentativas de repetição, o código recebe o erro, portanto, ele ainda precisa de um plano.

Como testar se seu aplicativo lida com o 429

Você raramente vê um 429 enquanto se desenvolve. A API é rápida, você é o único usuário e seus dados de teste são pequenos. Portanto, a maneira como você testa o tratamento do 429 decide se você encontra os bugs antes que seus usuários os encontrem.

Approach O que você encontra Do que você sente falta
Aguardar o ambiente de produção Falhas reais Tudo, até que um usuário o acione
Fazer mock da API em seus testes ou deixar seu agente de codificação escrever o mock Se o ramo de repetição é executado Os códigos de status, cabeçalhos e corpos de erro reais da API e a política de repetição do SDK. Seu aplicativo também precisa de uma opção somente de teste para acessar o mock.
Chame a API real até que a API real aplique limite de taxa Comportamento real Você não pode disparar um 429 sob demanda, e você usa sua cota real
Interceptar o tráfego real do aplicativo e retornar 429s sob demanda URLs reais, seu SDK real e política de repetição e o próprio formato 429 da API Nada no aplicativo muda, portanto, seu código não é testado em isolamento. Deixe isso para seus testes unitários.

Experimente no seu aplicativo

Dev Proxy intercepta as solicitações do aplicativo para as APIs escolhidas e retorna 429s, com os próprios cabeçalhos e o formato de erro da API, enquanto seu aplicativo continua chamando as URLs reais. Ele também informa quando seu aplicativo faz nova tentativa antes que o Retry-After tempo termine.

Baixe a predefinição para a API que seu aplicativo chama e inicie o Proxy de Desenvolvimento com ela:

devproxy config get github-rate-limiting
devproxy --config-file "~dataFolder/configs/github-rate-limiting/.devproxy/devproxyrc.json"
API Preset
GitHub github-rate-limiting
OpenAI openai-throttling
Anthropic anthropic-throttling
Microsoft Graph (OneDrive e SharePoint: /drive, /shares, /sites) microsoft-graph-rate-limiting

Em seguida, execute seu aplicativo como de costume e observe o que ele faz. Para instalar o Dev Proxy, consulte Configurar o Dev Proxy.

Próximas Etapas 

Teste se meu aplicativo manipula a limitação corretamente

Consulte também

  • Última atualização em