429 Pedidos a Mais: o que significa e como lidar com isso

Uma API retorna 429 Too Many Requests quando a sua aplicação enviou mais pedidos do que a API permite num determinado período de tempo. O pedido em si está bem. Enviaste-o demasiadas vezes, por isso a API rejeitou-o. Se esperar e enviar novamente, normalmente funciona. A resposta costuma incluir um Retry-After cabeçalho que indica quanto tempo deve esperar. Para mais informações, consulte o RFC 6585, secção 4.

Cada API implementa limites de pedidos de forma diferente. O código de estado, os cabeçalhos e o corpo do erro variam, por isso o código que lida corretamente com uma API pode gerir mal a seguinte.

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 é 0, caso contrário pelo menos 1 minuto A 403 pode ser um limite de taxa ou uma permissão em falta. Leia os cabeçalhos para os distinguir.
OpenAI 429 retry-after Alguns 429, como credit_balance_exhausted, significam que tentar novamente não vai ajudar. Verifique error.code.
Anthropic 429 retry-after Um 429 com limite de gasto não retry-after tem e continua a falhar até o acesso recomeçar. Uma API sobrecarregada devolve 529, não 429.
Gráfico da Microsoft 429 Retry-After (segundos) Os limites variam consoante o serviço, por exemplo, SharePoint e Outlook.

Como lidar com um 429

  1. Decide se deves voltar a tentar ou não. Se o erro indicar que a sua quota, os seus créditos ou o seu limite de despesa se esgotaram, voltar a tentar não ajudará. Informa o utilizador, e avisa-te.
  2. Espera o tempo que a API pedir. Se a resposta for Retry-After, espera esse tempo. É um número de segundos ou uma data HTTP. Se a API usar cabeçalhos de limite de taxa em vez disso, como no x-ratelimit-resetGitHub, espere até ao momento do reset.
  3. Caso contrário, afasta-te. Sem uma dica da API, tenta novamente com backoff exponencial e jitter aleatório, e pára após algumas tentativas.
  4. Diz ao utilizador o que está a acontecer. "Ocupado, a tentar novamente em 5 segundos" é melhor do que um spinner que nunca acaba.
  5. Abranda antes dos próximos 429. Se a API enviar cabeçalhos de limite de taxa, use a contagem restante para ajustar o ritmo dos seus pedidos.
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 os erros 429 por ti. Por exemplo, o SDK Python da OpenAI tenta 2 vezes por defeito, e o handler de resiliência padrão .NET tenta 3 vezes e respeita Retry-After. Quando o SDK fica sem tentativas, o teu código recebe o erro, por isso ainda precisa de um plano.

Como testar se a sua aplicação lida com o erro 429

Raramente se vê um 429 enquanto se desenvolve. A API é rápida, és o único utilizador e os teus dados de teste são pequenos. Assim, a forma como testas o tratamento do 429 decide se encontras os bugs antes dos teus utilizadores.

Approach O que encontra O que sentes falta
Aguardar o ambiente de produção Fracassos reais Tudo, até que um utilizador lhe clique
Simula a API nos teus testes, ou deixa o teu agente de programação escrever o mock Se o seu branch de retry for executado Os códigos de estado reais, cabeçalhos e corpos de erro da API, e a política de retentativas do teu SDK. A tua aplicação também precisa de um switch só de teste para chegar ao mock.
Faz pedidos à API real até que te limite Comportamento real Não podes ativar um 429 a pedido e acabas por gastar a tua quota real
Interceta o tráfego real da tua aplicação e devolve os 429s a pedido URLs reais, o seu SDK real e política de retentativas, e o próprio formato 429 da API Nada na tua aplicação muda, por isso não testa o teu código isoladamente. Guarda os testes unitários para isso.

Experimente na sua app

O Dev Proxy interceta os pedidos da sua aplicação para as APIs que escolhe e devolve 429s, com os próprios cabeçalhos e formato de erro da API, enquanto a sua aplicação continua a chamar os URLs reais. Também te avisa quando a tua aplicação tenta novamente antes de o tempo Retry-After acabar.

Descarregue a predefinição da API que a sua aplicação chama e inicie o Dev Proxy 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

Depois executa a tua aplicação como de costume e vê o que faz. Para instalar Dev Proxy, consulte Configurar Dev Proxy.

Passos seguintes

Teste que a minha aplicação lida com o controle de fluxo corretamente

Ver também

  • Última atualização a