RateLimit y RateLimit-Policy frente a X-RateLimit-*: cómo leer las cabeceras de cuota que envíe una API

Qué es

RFC 9110 define una única cabecera estandarizada y determinante para este fin: "the Retry-After field value can be either an HTTP-date or a number of seconds to delay after receiving the response" (el valor puede ser una fecha HTTP o un número de segundos de espera tras recibir la respuesta), formalmente Retry-After = HTTP-date / delay-seconds. RFC 9110 describe su significado en las respuestas 503 y 3xx, y RFC 6585 permite incluirla en una 429. Indica cuánto tiempo el cliente "ought to wait" (debería esperar): es el valor del propio servidor, no una estimación del lado del cliente. Aparte de esto, un Internet-Draft activo del IETF, draft-ietf-httpapi-ratelimit-headers (revisión -11 en el momento de escribir esto), propone dos campos informativos para usarlos antes de que se limite una petición: RateLimit-Policy, que describe la cuota (por ejemplo RateLimit-Policy: "default";q=100;w=60, es decir, 100 peticiones por ventana de 60 segundos bajo una política llamada "default"), y RateLimit, que informa de la cuota disponible en ese momento bajo dicha política (por ejemplo RateLimit: "default";r=50;t=30: 50 unidades de cuota disponibles, para usar dentro de una ventana efectiva de 30 segundos). El borrador advierte de que la ventana efectiva "does not imply anything about when the server will increase the available quota" (no implica nada sobre cuándo ampliará el servidor la cuota disponible), de modo que t no es una marca de tiempo de reinicio. Sigue siendo un borrador: según el proceso del IETF, un Internet-Draft es "valid for a maximum of six months" (válido durante un máximo de seis meses) y no es adecuado citarlo como referencia estable, así que la sintaxis exacta de los campos puede cambiar antes de su publicación. En la práctica, la mayoría de las API en producción son anteriores a este borrador o lo ignoran, y envían sus propias cabeceras con nombres como x-ratelimit-limit, x-ratelimit-remaining y x-ratelimit-reset (la API REST de GitHub es un ejemplo documentado), con un formato que el borrador no regula y que varía según el proveedor.

Por qué importa

Un cliente genérico que se integre con muchas API se encontrará con las tres situaciones: una cabecera informativa en vías de estandarización, una cabecera ad hoc propia de cada proveedor, o nada más que Retry-After en la 429 final. Por eso necesita un orden de reserva que no presuponga la presencia de ninguna de ellas.

Cómo aplicarlo

• Trata Retry-After como la referencia definitiva siempre que esté presente, en cualquier código de estado que la incluya; interpreta las dos formas (segundos enteros y una HTTP-date) y espera al menos ese tiempo antes de reintentar.
• Si hay RateLimit/RateLimit-Policy, interprétalas de forma defensiva (son un borrador: los nombres de campo, los delimitadores e incluso los nombres de las cabeceras han cambiado entre revisiones) y úsalas para reducir el ritmo antes de que la cuota llegue a cero.
• Si solo aparecen cabeceras propias del tipo x-ratelimit-*, considera que su presencia y su significado son específicos de esa API: no des por hecho que los mismos nombres de campo signifiquen lo mismo en otro proveedor.
• Cuando no aparece ninguna de las anteriores, recurre al retroceso exponencial con jitter ante 429/503, ya que RFC 9110 no exige ninguna cabecera informativa.

Trampas

Fijar en el código un analizador para la sintaxis actual del borrador de RateLimit/RateLimit-Policy y tratarla como un estándar definitivo; el propio borrador advierte expresamente contra citarlo "as reference material... other than as work in progress" (como material de referencia, salvo como trabajo en curso). Ignorar un valor de Retry-After porque una cabecera informativa sugería que quedaba más cuota: Retry-After refleja lo que el servidor ha decidido realmente, y eso puede diferir de una estimación informativa enviada antes.