Anuncia la cuota restante antes de que el agente llegue al límite

Informa en cada respuesta, no solo en el 429, la cuota que le queda a quien llama y la ventana de tiempo que cubre, para que un agente pueda bajar el ritmo antes de que lo limiten.

Por qué

Un agente que procesa una cola de trabajo, como 300 reembolsos, no tiene una noción propia del ritmo. Si la única señal es un 429 cuando el límite ya se agotó, aprende el límite chocando con él, y el lote falla a la mitad con algunos reembolsos hechos y otros no. HTTP ya tiene una forma de decir cuánto esperar: el Retry-After de la RFC 9110 le indica al cliente cuánto debería esperar antes de la siguiente petición. Pero llega solo después del fallo. El borrador de campos de cabecera RateLimit del grupo de trabajo HTTPAPI del IETF (draft-ietf-httpapi-ratelimit-headers-11, mayo de 2026, pensado como Standards Track) adelanta la señal: RateLimit-Policy anuncia la política de cuota y RateLimit la cuota que queda disponible, lo que permite a los clientes evitar que los limiten. La API REST de GitHub ya envía esto en las respuestas normales (x-ratelimit-limit, -remaining, -used, -reset, -resource) y pide a los clientes usar esas cabeceras para ajustar el ritmo y retroceder, sin depender de un conteo exacto, y respetar retry-after cuando aparece. AX-SYS-21 decide cuál es el tope; este principio le dice al agente dónde está frente a ese tope mientras todavía tiene tiempo de ajustarse.

Haz

Envía la política y la cuota restante con su ventana de tiempo en cada respuesta, y agrega Retry-After cada vez que limites.

No hagas

Ocultar los límites hasta el primer 429, ni devolver un 429 sin ninguna pista de cuándo volver a intentar.

Artefacto

HTTP/1.1 200 OK
Content-Type: application/json
RateLimit-Policy: "refunds";q=100;w=60
RateLimit: "refunds";r=4;t=38

HTTP/1.1 429 Too Many Requests
RateLimit: "refunds";r=0;t=21
Retry-After: 21

Con 4 reembolsos disponibles para los próximos 38 segundos, el agente espacia sus siguientes llamadas en lugar de lanzarlas todas y fallar en la quinta.