Encabezado Retry-After: cuánto tiempo debe esperar antes de volver a intentarlo

Retry-After es un encabezado de respuesta HTTP que indica a la aplicación cuánto tiempo debe esperar antes de enviar la siguiente solicitud. El valor es un número de segundos o una fecha HTTP. Cuando una API lo envía, es la respuesta más fiable a ¿cuándo puedo volver a intentarlo?, ya que procede del servidor que rechazó tu solicitud. Para obtener más información, vea RFC 9110, sección 10.2.3.

Qué aspecto tiene Retry-After

El encabezado tiene dos formatos. Tu aplicación debe administrar ambas situaciones.

Los servidores envían Retry-After con estos códigos de estado:

El encabezado es opcional. Algunas APIs usan sus propias cabeceras en su lugar. Por ejemplo, GitHub indica cuándo se restablece el límite con x-ratelimit-reset. Para obtener más información, consulta Límite de frecuencia de la API de GitHub superado.

Cómo controlar Retry-After

1. Lee ambos formatos. Si el valor es un número, se mide en segundos. De lo contrario, analízalo como una fecha y resta la hora actual. Si la fecha ya está en el pasado, puede volver a intentarlo de inmediato.
2. Espere al menos el tiempo que indique el encabezado. Si lo intentas antes de tiempo, normalmente obtendrás otro 429 o 503. Algunas API siguen contando las solicitudes mientras te limitan la tasa, por lo que los reintentos tempranos pueden hacer que la espera sea más larga. Por ejemplo, consulta Guía de limitación de Microsoft Graph.
3. Recurre a la estrategia de retroceso con fluctuación cuando falte el encabezado. Duplica el tiempo de espera después de cada intento fallido, añade una cantidad aleatoria para que muchos clientes no vuelvan a intentarlo al mismo tiempo y limita el tiempo de espera máximo.
4. Limita tus reintentos. Tras varios intentos, devuelve el error al solicitante.
5. Compruebe que un reintento puede ayudar. Algunas API devuelven 429 cuando se agotan tus créditos o se alcanza tu límite de gasto. Esperar no arreglará eso. Para obtener un ejemplo, vea OpenAI insufficient_quota y 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);
}

Qué hacen los SDK populares

Muchos SDK administran Retry-After por ti, pero solo hasta que se agoten los reintentos. Entonces, tu código recibe el error.

Consulta la documentación de tu SDK para conocer la directiva exacta y comprueba qué ocurre cuando falla el último reintento.

Cómo probar que la aplicación controla Retry-After

Rara vez tienes un Retry-After mientras desarrollas y, cuando lo tienes, no puedes controlar su valor. Por lo tanto, la forma en que pruebes esto determinará si detectas los errores antes que tus usuarios.

Pruébalo en tu app

Dev Proxy intercepta las solicitudes de tu aplicación a las API que elijas y devuelve 429 respuestas con un encabezado Retry-After, mientras tu aplicación sigue llamando a las URL reales. El RetryAfterPlugin recuerda cuándo se puede reintentar cada solicitud limitada. Si la aplicación llama a la misma dirección URL antes de ese momento, Dev Proxy lo notifica y limita la solicitud de nuevo. El complemento realiza un seguimiento únicamente de las 429 respuestas.

En tu archivo de errores para el GenericRandomErrorPlugin, establece el Retry-After valor de una 429 respuesta en @dynamic, y Dev Proxy completará el número de segundos y lo controlará por ti.

Para probarlo, descarga una configuración preestablecida que utilice ambos complementos e inicia Dev Proxy con ella:

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

A continuación, ejecute la aplicación como de costumbre y observe lo que hace. Para instalar Dev Proxy, consulte Configurar Dev Proxy.

Pasos siguientes

Consulte también

• 429 Demasiadas solicitudes: lo que significa y cómo controlarlo
• Cómo gestionar la limitación de velocidad de la API
• RetryAfterPlugin
• GenericRandomErrorPlugin
• Prueba de reintentos y tiempos de espera en aplicaciones de .NET