Aivorab
Ilustración editorial: Cómo las APIs pequeñas deberían comunicar límites de tasa: Guía práctica de cabeceras estándar

Rendimiento API · Limitación de tasa · Cabeceras HTTP · Estándares IETF · Diseño API

Cómo las APIs pequeñas deberían comunicar límites de tasa: Guía práctica de cabeceras estándar

Aprende a implementar cabeceras RateLimit-Limit, RateLimit-Remaining y Retry-After usando el borrador estándar del IETF, reduciendo tickets de soporte mientras mantienes los vectores de abuso contenidos.

Publicado:

Deje de Adivinar: Cabeceras de Límite de Tasa que Realmente Ayudan a sus Desarrolladores

Si administra una API pequeña, sus límites de tasa no son una característica de seguridad—son un problema de comunicación. La mayoría de los desarrolladores independientes y equipos pequeños descubren sus límites de la manera difícil: una respuesta 429, un ticket de soporte confundido, y un fin de semana depurando lógica de reintentos que debería haber sido obvia desde el principio.

La buena noticia es que el IETF ha estado trabajando en estandarizar cabeceras de límite de tasa durante años. El borrador draft-ietf-httpapi-ratelimit-headers define un enfoque limpio y estructurado que las APIs pequeñas pueden adoptar sin sobreingeniería. La aún mejor noticia: servicios importantes como GitLab, CircleCI y OKX ya envían estas cabeceras en producción. No necesita esperar un RFC para empezar a hacer lo correcto.

La Forma Anterior: Cabeceras X-RateLimit-*

Antes del borrador del IETF, el estándar de facto era un conjunto de cabeceras no estándar con prefijo X-:

GitHub usa esta convención. Funciona. Pero tiene problemas. El prefijo X- señala “experimental” en semántica HTTP, lo que crea ambigüedad sobre si estas cabeceras son garantías contractuales confiables o detalles de implementación interna. Más importante aún, el formato es no estructurado—solo enteros planos sin forma de expresar políticas de ventana, límites concurrentes múltiples, o metadatos de cuota.

El Nuevo Estándar: Cabeceras RateLimit-*

El borrador del IETF introduce tres cabeceras sin el prefijo X-, usando sintaxis de Campos Estructurados HTTP:

Una respuesta simple podría verse así:

RateLimit-Limit: 500
RateLimit-Remaining: 487
RateLimit-Reset: 23

O con una política de ventana explícita:

RateLimit-Limit: 120; w=60
RateLimit-Remaining: 15
RateLimit-Reset: 23

El parámetro w le dice a los clientes la duración de la ventana en segundos. Esto elimina la ambigüedad de los timestamps Unix—los clientes ya no necesitan calcular diferencias de tiempo ni preocuparse por la desincronización de relojes entre servidor y cliente.

Para APIs con múltiples niveles de límite de tasa (por minuto y por hora, por ejemplo), puede enviar múltiples políticas:

RateLimit-Limit: 100; w=60, 1000; w=3600
RateLimit-Remaining: 45, 892
RateLimit-Reset: 12, 1847

Este formato estructurado es compatible hacia atrás en la práctica—los clientes que entienden las nuevas cabeceras las usan, y los clientes que solo conocen las cabeceras X-RateLimit-* continúan funcionando con respuestas heredadas.

Qué Exponer: El Contrato Mínimo Viable

Las APIs pequeñas deben exponer exactamente tres cabeceras en cada respuesta exitosa:

  1. RateLimit-Limit (o X-RateLimit-Limit si prefiere compatibilidad heredada)
  2. RateLimit-Remaining
  3. RateLimit-Reset

Eso es todo. No agregue cabeceras personalizadas como X-Quota-Used o X-RateLimit-Window a menos que tenga una razón específica. Cada cabecera adicional aumenta la complejidad de implementación del cliente y la carga de soporte.

El valor Reset debe ser segundos-hasta-el-reinicio, no un timestamp Unix. Este es el cambio de mayor impacto que puede hacer. Los clientes pueden programar directamente su próxima solicitud sin ningún cálculo. Un cliente que ve RateLimit-Reset: 8 sabe que debe esperar aproximadamente 8 segundos antes de reintentar, no que debe verificar la hora actual y restar de algún valor de época arbitrario.

Qué Mantener Privado

No exponga:

La Cabecera Retry-After: Su Red de Seguridad

Cuando un cliente excede su límite, la cabecera Retry-After (definida en RFC 7231) les dice cuánto tiempo esperar. Esta es su cabecera más importante para respuestas 429:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 30

Note que Retry-After y RateLimit-Reset deben coincidir. Si su RateLimit-Reset dice 30 segundos, su Retry-After también debe ser 30. El desacuerdo entre estas cabeceras crea confusión y tickets de soporte.

Algunas APIs envían Retry-After como una fecha HTTP (un timestamp futuro). Para limitación de tasa, segundos-hasta-el-reinicio es casi siempre más claro. Los clientes pueden analizar enteros más rápido que cadenas de fecha, y la semántica es inequívoca.

Compromisos de Implementación

Campos Estructurados vs Enteros Planos

El borrador del IETF usa Campos Estructurados HTTP, que permite parámetros como ; w=60. Esto es más expresivo que enteros planos pero requiere que los clientes analicen sintaxis estructurada. Para una API pequeña con una audiencia de desarrolladores pequeña, los enteros planos son perfectamente aceptables. El formato estructurado es futuro-proof, pero no deje que lo perfecto sea enemigo de lo bueno.

Enviar Cabeceras en Todas las Respuestas vs Solo cuando es Relevante

Envíe cabeceras de límite de tasa en cada respuesta 2xx. No las restrinja a solicitudes “interesantes”. Un cliente que solo ve cabeceras en el 90% de las respuestas no puede rastrear su cuota de manera confiable. La consistencia construye confianza.

Límites por-Endpoint vs Globales

Si su API tiene diferentes límites de tasa por endpoint (por ejemplo, los endpoints de búsqueda son más costosos), tiene dos opciones:

  1. Cabeceras por-endpoint: Incluya el límite relevante para el endpoint actual. Esto es más simple pero significa que los clientes deben rastrear límites a través de endpoints por separado.
  2. Cabeceras globales con especificidad por-endpoint: Incluya tanto un límite global como límites específicos por-endpoint. Esto es más complejo pero da a los clientes una imagen completa.

Para APIs pequeñas, las cabeceras por-endpoint son suficientes. La mayoría de los clientes solo interactuarán con un puñado de endpoints de todos modos.

Cómo un Buen Diseño de Cabeceras Reduce Tickets de Soporte

Considere dos escenarios:

Escenario A: Su API devuelve X-RateLimit-Limit: 1000 sin conteo restante ni hora de reinicio. Un desarrollador alcanza el límite a las 2:47 PM y no tiene idea de cuándo puede reintentar. Abre un ticket de soporte preguntando “cuándo se reiniciará mi límite de tasa?”

Escenario B: Su API devuelve RateLimit-Remaining: 3 y RateLimit-Reset: 12. El mismo desarrollador ve tres solicitudes restantes y sabe que la ventana se reinicia en 12 segundos. Reduce la velocidad de su cliente y continúa. Sin ticket.

La diferencia no es su política de límite de tasa. Es su diseño de cabeceras. El Escenario B requiere la misma lógica de backend que el Escenario A—solo mejor comunicación.

Preguntas Frecuentes

P: Debería soportar tanto X-RateLimit- como RateLimit-?**

R: Sí, si su base de clientes incluye consumidores de documentación antigua. Envíe ambos conjuntos de cabeceras durante un período de transición. Una vez que esté seguro de que los clientes han migrado, elimine las variantes X-. La mayoría de los clientes HTTP y SDKs modernos ya analizan las nuevas cabeceras.

P: Qué hago si mi ventana de límite de tasa no es un intervalo fijo?

R: El parámetro w es opcional. Puede enviar RateLimit-Limit: 100 sin especificación de ventana si sus límites son basados en ventana deslizante o bucket de tokens. Las cabeceras Remaining y Reset aún proporcionan información útil incluso sin una ventana explícita.

P: Reemplaza el borrador del IETF el Retry-After del RFC 7231?

R: No. Retry-After es una cabecera de propósito general para cualquier respuesta throttled. Las cabeceras RateLimit la complementan proporcionando información proactiva de cuota antes de que ocurra un 429. Use ambas.

P: Cómo manejo límites de tasa autenticados vs no autenticados?

R: Devuelva diferentes valores de RateLimit-Limit basados en la autenticación. Una solicitud no autenticada podría mostrar RateLimit-Limit: 60 mientras una autenticada muestra RateLimit-Limit: 5000. Las cabeceras reflejan la cuota real para esa solicitud específica, que es exactamente lo que los clientes necesitan.

Conclusión

Las APIs pequeñas deben adoptar la convención de cabeceras RateLimit-* del borrador del IETF. Es simple, expresiva, y ya probada en producción por servicios como GitLab y CircleCI. La migración desde las cabeceras X-RateLimit-* es directa, y la reducción de tickets de soporte es inmediata. Sus desarrolladores se lo agradecerán—no con palabras, sino con el silencio de no necesitar contactarlo en absoluto.

Fuentes