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 la envía, es la respuesta más confiable a "¿cuándo puedo intentarlo de nuevo?" porque procede del servidor que rechazó la 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. La aplicación debe gestionar ambas.

Formato Example Qué significa
Seconds Retry-After: 120 Espere 120 segundos (2 minutos) desde que recibió la respuesta. El valor es un número entero no negativo.
Fecha HTTP Retry-After: Fri, 31 Dec 1999 23:59:59 GMT No envíe la solicitud de nuevo antes de esta vez. La fecha siempre está en GMT.

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

Status ¿Qué Retry-After significa? Source
429 Too Many Requests Cuánto tiempo debe esperar antes de enviar una nueva solicitud. El servidor puede incluirlo. RFC 6585, sección 4
503 Service Unavailable Cuánto tiempo se espera que el servicio no esté disponible. El servidor puede incluirlo. RFC 9110, sección 15.6.4
413 Content Too Large Si la condición es temporal, el servidor debe indicar después de cuánto tiempo terminará. RFC 9110, sección 15.5.14
Cualquier 3xx redirección Tiempo mínimo de espera antes de seguir la redirección. RFC 9110, sección 10.2.3

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, consulte se ha superado el límite de velocidad de la API de GitHub.

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. Volver a intentarlo antes suele darte 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, consulte Microsoft Graph guía de limitación.
  3. Recurra a un backoff con variación aleatoria cuando falte la cabecera. 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. Después de algunos intentos, devuelva el error a la función que llama.
  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);
}

Muchos SDK controlan Retry-After automáticamente, pero solo hasta que se agoten los reintentos. A continuación, el código recibe el error.

SDK Lo que hace de forma predeterminada
.NET controlador de resistencia estándar Reintenta 408, 429y 5xx responde hasta 3 veces con retroceso exponencial y vibración. Usa Retry-After para el retraso porque ShouldRetryAfterHeader tiene como valor predeterminado true.
SDK de Microsoft Graph Úselo Retry-After cuando esté presente y vuelva a la espera exponencial cuando no lo esté. Las solicitudes dentro de un lote JSON no se reintentan automáticamente.
SDK de OpenAI Python Reintenta los errores de conexión y 408las respuestas , 409, 429y 5xx 2 veces con un retroceso exponencial corto. Establezca max_retries para cambiarlo.

Compruebe la documentación del SDK para obtener la directiva exacta y pruebe lo que sucede después de que se produzca un error en 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 de probar esto decide si encuentra los errores antes de que los usuarios lo hagan.

Approach Lo que encuentras Lo que te pierdes
Esperar a que se publique en producción Fallos reales Todo, hasta que un usuario haga clic en ello
Simula la API en tus pruebas o deja que el agente de codificación escriba el simulacro Si el código analiza el encabezado Si su cliente HTTP real o SDK espera lo suficiente y qué envía realmente la API. La aplicación también necesita una opción solo para pruebas para llegar al mock.
Llame a la API real hasta que la API le aplique una limitación de tasa. Comportamiento real No se puede desencadenar una respuesta con limitación de tasa a petición y se usa la cuota real.
Interceptar el tráfico real de la aplicación y devolver respuestas limitadas a petición Si el SDK real y la directiva de reintento esperan siempre y cuando el encabezado indique Nada en la aplicación cambia, por lo que no prueba el código de forma aislada. Mantenga las pruebas unitarias para eso.

Pruébalo en tu app

Dev Proxy intercepta las solicitudes de la aplicación a las API que elija y devuelve 429 respuestas con un Retry-After encabezado, mientras que la aplicación sigue llamando a las direcciones URL reales. 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 solo realiza un seguimiento de las respuestas 429.

En el archivo de errores de GenericRandomErrorPlugin, establece el valor de Retry-After de una respuesta 429 en @dynamic, y Dev Proxy completa el número de segundos y hace un seguimiento de ellos.

Para probarlo, descargue un valor preestablecido que use ambos complementos e inicie Dev Proxy con él:

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

Prueba de que mi aplicación controla la limitación correctamente

Consulte también

  • Se actualizó por última vez el