Retroceder como cliente: Retry-After, las cabeceras RateLimit y presupuestos por host

Objetivo

Mantenerse dentro de los límites de un servidor sin adivinar, recuperarse de un límite alcanzado sin empeorarlo, y evitar que las numerosas peticiones pequeñas de un agente se conviertan en una caída del servicio o en el bloqueo de la clave.

Requisitos previos

Un cliente capaz de inspeccionar códigos de estado y cabeceras, de esperar, y de mantener un poco de estado por host. Conocer qué peticiones son idempotentes.

Pasos

1. Ante 429 Too Many Requests (RFC 6585) o 503 Service Unavailable, buscar Retry-After. La RFC 9110 la define como un número de segundos o como una fecha HTTP; esperar ese tiempo y reintentar una vez. Un Retry-After es una instrucción del servidor y prevalece sobre cualquier programación local.
2. Sin Retry-After, retroceder de forma exponencial desde un retardo base con jitter completo, limitar el retardo máximo y limitar el número de intentos. Contar los intentos por petición, no por sesión, y desistir con un error claro en cuanto se alcance el límite.
3. Leer las cabeceras informativas cuando estén presentes. El borrador del IETF sobre los campos de cabecera RateLimit define un campo RateLimit que lleva la cuota restante y los segundos hasta el reinicio, y un campo RateLimit-Policy que describe la política de cuota; un cliente que los lea puede reducir el ritmo antes del primer 429. Tratarlos como indicios que pueden estar ausentes o cambiar de forma entre servidores, y recurrir al paso 2 como respaldo.
4. Mantener un presupuesto por host y por credencial: un número máximo de peticiones en vuelo y un intervalo mínimo, que se ajusta a la baja con cada 429 y solo se relaja lentamente al alza. Los agentes en paralelo que comparten una clave comparten un mismo presupuesto; coordinar mediante un contador compartido o una cola, en lugar de que cada uno retroceda por su cuenta.
5. No reintentar nunca a ciegas una escritura no idempotente. Adjuntar una clave de idempotencia cuando la API la admita, para que un reintento tras un tiempo de espera agotado no pueda duplicar el efecto; si no, consultar si el efecto ya se produjo antes de reintentar.
6. Registrar cada 429 con el host, la clase de endpoint y la espera aplicada; un patrón de 429 en un endpoint es una señal de diseño (pedir menos, cachear más, usar un endpoint por lotes), no un motivo para subir el límite de reintentos.
7. Preferir las peticiones condicionales y la caché para las lecturas: un 304 Not Modified es barato para ambas partes y normalmente no cuenta contra una cuota igual que una respuesta completa, aunque eso es algo que corresponde declarar a la política del servidor.

Resultado esperado

Los límites alcanzados se vuelven raros y se autocorrigen, los reintentos nunca duplican una escritura, y el servicio percibe un cliente que reduce el ritmo cuando se le pide, en lugar de uno que insiste con más fuerza.

Límites y base de verificación

Síntesis de estándares y una disciplina de cliente propuesta; sin medición. El borrador de la cabecera RateLimit es eso, un borrador: los nombres de los campos y su semántica pueden cambiar hasta su publicación, y muchos servidores envían en su lugar sus propias cabeceras específicas de proveedor.