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 da 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 você, de modo que as novas tentativas antecipadas podem tornar a espera mais longa. Por exemplo, consulte diretrizes de limitação do Microsoft Graph.
  3. Recorra à retirada com tremulação 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 retirada exponencial e tremulação. 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 a retirada 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 duas vezes com uma retirada exponencial curta. 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
Simule a API em seus testes ou deixe seu agente de codificação escrever a simulação 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 a simulação.
Faça chamadas à API real até atingir o limite de taxa Comportamento real Você não pode disparar uma resposta com limitação 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.

Testar no seu aplicativo

O Dev Proxy intercepta as requisições do seu aplicativo para as APIs que você escolher e retorna respostas 429 e 503 com um cabeçalho Retry-After, enquanto o seu aplicativo continua fazendo chamadas para as URLs reais. O RetryAfterPlugin lembra quando cada solicitação com limitação pode ser repetida. Se seu aplicativo chamar a mesma URL antes desse horário, o Proxy de Desenvolvimento a registrará e limitará a solicitação novamente.

No arquivo de erros do GenericRandomErrorPlugin, defina o valor Retry-After de uma resposta como @dynamic, e o Dev Proxy preencherá o número de segundos e fará o rastreamento para você. Isso funciona com qualquer código de status, como 429 ou 503.

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 

Testar se meu aplicativo lida corretamente com a limitação

Consulte também

  • Última atualização em