O cabeçalho Retry-After: quanto tempo esperar antes de tentar novamente

Retry-After é um cabeçalho de resposta HTTP que informa ao aplicativo quanto tempo aguardar antes de enviar a próxima solicitação. O valor é um número de segundos ou uma data HTTP. Quando uma API envia essa informação, é a resposta mais confiável para "quando posso tentar novamente?" porque ela vem do servidor que recusou sua solicitação. Para obter mais informações, consulte RFC 9110, seção 10.2.3.

Como é o Retry-After

O cabeçalho tem dois formatos. Seu aplicativo precisa lidar com ambos.

Format Example O que significa
Seconds Retry-After: 120 Aguarde 120 segundos (2 minutos) a partir de quando você recebeu a resposta. O valor é um número inteiro não negativo.
data HTTP Retry-After: Fri, 31 Dec 1999 23:59:59 GMT Não envie a solicitação novamente antes desse horário. A data está sempre em GMT.

Os servidores enviam Retry-After com estes códigos de status:

Status O que Retry-After significa Source
429 Too Many Requests Quanto tempo aguardar antes de enviar uma nova solicitação. O servidor pode incluí-lo. RFC 6585, seção 4
503 Service Unavailable Por quanto tempo o serviço deve ficar indisponível. O servidor pode incluí-lo. RFC 9110, seção 15.6.4
413 Content Too Large Se a condição for temporária, o servidor deverá dizer após quanto tempo passará. RFC 9110, seção 15.5.14
Qualquer 3xx redirecionamento O tempo mínimo para aguardar antes que o redirecionamento ocorra. RFC 9110, seção 10.2.3

O cabeçalho é opcional. Em vez disso, algumas APIs usam seus próprios cabeçalhos. Por exemplo, GitHub informa quando o limite é redefinido com x-ratelimit-reset. Para obter mais informações, consulte limite de taxa da API do GitHub excedido.

Como lidar com Retry-After

  1. Leia os dois formatos. Se o valor for um número, é em segundos. Caso contrário, analise-a como uma data e subtraia o horário atual. Se a data já estiver no passado, você poderá tentar novamente imediatamente.
  2. Aguarde pelo menos o tempo que o cabeçalho indicar. Tentar novamente antes geralmente lhe dá outro 429 ou 503. Algumas APIs continuam contando suas solicitações enquanto restringem suas requisições, de modo que as novas tentativas antecipadas podem fazer a espera mais longa. Por exemplo, consulte diretrizes de limitação do Microsoft Graph.
  3. Recorra a backoff com jitter quando o cabeçalho estiver ausente. Dobre a espera após cada tentativa com falha, adicione uma quantidade aleatória para que muitos clientes não tentem novamente no mesmo momento e limite a espera.
  4. Limite o número de tentativas. Após algumas tentativas, retorne o erro ao chamador.
  5. Verifique se uma nova tentativa pode ajudar. Algumas APIs retornam 429 quando seus créditos se esgotam ou seu limite de gastos é atingido. Esperar não vai corrigi-los. Para ver um exemplo, consulte OpenAI insufficient_quota e credit_balance_exhausted.
function retryDelayMs(response, attempt) {
  const value = response.headers.get('retry-after');
  if (value) {
    const seconds = Number(value);
    const ms = Number.isNaN(seconds) ? Date.parse(value) - Date.now() : seconds * 1000;
    if (!Number.isNaN(ms)) {
      return Math.max(ms, 0);
    }
  }
  // No usable header: exponential backoff with jitter, capped at 30 seconds
  return Math.random() * Math.min(30_000, 1_000 * 2 ** attempt);
}

Muitos SDKs manipulam Retry-After para você, mas somente até ficarem sem tentativas. Em seguida, o código gera o erro.

SDK O que ele faz por padrão
.NET manipulador de resiliência padrão Tenta novamente as respostas 408, 429 e 5xx até 3 vezes com backoff exponencial e jitter. Ele usa Retry-After para o atraso porque ShouldRetryAfterHeader tem como padrão true.
SDKs do Microsoft Graph Use Retry-After quando estiver presente e volte para o backoff exponencial quando não estiver. As solicitações dentro de um lote JSON não são repetidas automaticamente.
OpenAI Python SDK Repete erros de conexão e respostas 408, 409, 429 e 5xx 2 vezes com um backoff exponencial curto. Defina max_retries para alterá-lo.

Verifique a documentação do SDK para obter a política exata e teste o que acontece depois que a última tentativa falhar.

Como testar se seu aplicativo manipula Retry-After

Você raramente obtém um Retry-After enquanto desenvolve e, quando o faz, não consegue controlar seu valor. Portanto, a maneira como você testa isso 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 seu código analisa o cabeçalho Se o seu cliente HTTP real ou SDK espera o suficiente, e o que a API realmente envia. Seu aplicativo também precisa de uma opção somente de teste para acessar o mock.
Faça chamadas à API real até atingir o limite de taxa Comportamento real Você não pode disparar uma resposta com limitação de taxa sob demanda e usar sua cota real
Interceptar o tráfego real do aplicativo e retornar respostas com limitação de taxa sob demanda Se o SDK real e a política de repetição aguardam pelo tempo indicado no cabeçalho Nada no aplicativo muda, portanto, ele não testa seu código de forma isolada. Mantenha seus testes de unidade para isso.

Teste no seu aplicativo

Dev Proxy intercepta as solicitações que seu aplicativo faz às APIs escolhidas e retorna 429 respostas com um Retry-After cabeçalho, enquanto seu aplicativo continua chamando as URLs reais. O RetryAfterPlugin lembra quando cada solicitação com limitação de taxa pode ser repetida. Se seu aplicativo chamar a mesma URL antes desse horário, o Dev Proxy a registrará e limitará a solicitação novamente. O plug-in rastreia apenas as respostas 429.

No arquivo de erros do GenericRandomErrorPlugin, defina o valor Retry-After de uma resposta 429 para @dynamic, e o Dev Proxy preencherá o número de segundos e o rastreará para você.

Para experimentá-lo, baixe uma predefinição que usa os dois plug-ins e inicie o Dev Proxy com ele:

devproxy config get openai-throttling
devproxy --config-file "~dataFolder/configs/openai-throttling/.devproxy/devproxyrc.json"

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