Rate limit en el cliente: token bucket, leaky bucket y límites por host — guía experta
Contenido del artículo
- Introducción: por qué el cliente necesita su propio rate limit
- Fundamentos: qué es el rate limit en el cliente y por qué no basta con el servidor
- Inmersión profunda: las familias de algoritmos y su matemática
- Método 1: token bucket en la práctica — implementación sin trampas ocultas
- Método 2: leaky bucket y gcra — cuando se necesita un flujo parejo
- Método 3: límites por host — registro, jerarquía y composición
- Método 4: el limitador y la rotación de ip — cómo contemplar el cambio de dirección en el modelo
- Errores típicos de diseño del rate limit del lado del cliente
- Herramientas y recursos para la implementación
- Casos y escenarios de aplicación
- Faq: respuestas a preguntas difíciles
- Conclusión: qué hacer a continuación
Introducción: por qué el cliente necesita su propio rate limit
Imagine que llega a un banco donde hay una sola ventanilla y detrás de usted se formó una fila de mil personas. Puede empujar, puede gritar, pero la capacidad de la ventanilla no va a aumentar por eso. Solo puede llegar a un ritmo razonable o recibir un rechazo. El rate limit del servidor (limitación de frecuencia de solicitudes) es ese cajero que, en algún momento, simplemente deja de atenderlo. Y el rate limit del lado del cliente es su decisión personal de no acercarse a la ventanilla con más frecuencia de la que físicamente puede atender.
Este artículo está dedicado por completo a los algoritmos. Deliberadamente no vamos a repetir material sobre cómo manejar el código 429 ni sobre cómo armar un backoff exponencial, ni vamos a discutir cuántos hilos lanzar. El enfoque aquí es otro: cómo calcular de antemano, antes de enviar la solicitud, si se puede enviar ahora y, si no, cuánto esperar. Esa matemática es la que separa a un cliente que «a veces recibe rechazos» de un cliente que trabaja durante años con la misma API sin irritar a sus dueños.
Qué aprenderá en este material:
- cómo están construidas las cuatro familias de algoritmos — fixed window, sliding window, token bucket y leaky bucket — y en qué se diferencian a nivel de comportamiento, no solo de nombre;
- por qué token bucket y GCRA (una variante de leaky bucket) se convirtieron en el estándar de facto y cómo implementarlos en una tarde sin errores de redondeo;
- cómo construir una jerarquía de límites: presupuesto global, presupuesto por host, por endpoint, por clave de autorización y por dirección IP de salida;
- cómo integrar la rotación de IP en el modelo del limitador sin romper ni las cuotas del servidor ni su propia telemetría;
- qué errores de diseño parecen inofensivos pero terminan en esperas infinitas, «estallidos» al inicio del minuto y fugas de memoria.
Vamos a hablar con lenguaje de ingeniero-mentor: con fórmulas, pero sin pedantería; con ejemplos, pero sin relleno. Si usted escribe un scraper, un SDK para una API ajena, una integración con un marketplace o un agregador que consulta cientos de hosts, vale la pena guardar esta guía en marcadores.
Fundamentos: qué es el rate limit en el cliente y por qué no basta con el servidor
Dos miradas sobre un mismo problema
El rate limit del servidor protege la infraestructura del dueño de la API: cuenta sus solicitudes y responde con un rechazo cuando la cuota se agota. El rate limit del cliente resuelve otra tarea: no llegar al rechazo. La diferencia es de fondo. El servidor reacciona a posteriori: la solicitud ya salió, el canal está ocupado, el log se ensució, la reputación del cliente se dañó un poco. El cliente, en cambio, actúa de forma preventiva: conoce (o estima) el presupuesto y lo gasta con cuidado.
¿Por qué no basta con confiar en los rechazos del servidor y reintentar? Porque cada intento rechazado es una conexión gastada, un token de autorización gastado, una línea en el registro de seguridad ajeno y, por lo general, un empeoramiento de su posición en los sistemas de protección adaptativos. El cliente que respeta el ritmo por sí mismo se ve, ante el servidor, como un socio bien educado. Y el cliente que «prueba hasta que lo dejen pasar» se ve como una fuente de problemas. Adivine a quién van a limitar más duro en la próxima revisión de políticas.
Terminología básica
- Rate (velocidad): la frecuencia estable de solicitudes, por ejemplo «diez solicitudes por segundo». Es lo que el servidor está dispuesto a aceptar de forma indefinida.
- Burst (ráfaga): cuántas solicitudes se pueden enviar de inmediato, seguidas, sin esperar a que se reponga el cupo. El servidor suele tolerar ráfagas cortas si no se viola la velocidad promedio.
- Ventana (window): el intervalo de tiempo en el que se cuentan las solicitudes: un segundo, un minuto, una hora, un día.
- Cuota (quota): la cantidad máxima de solicitudes en la ventana. La cuota dividida por la duración de la ventana es la velocidad promedio.
- Clave de límite (limit key): el criterio con el que el servidor agrupa las solicitudes: dirección IP, token, cuenta, par «host más endpoint». Un mismo cliente casi siempre cae a la vez bajo varias claves.
- Costo (cost): el peso de la solicitud. Algunas API cuentan una búsqueda como diez unidades y la lectura de una ficha como una.
El principio central: el limitador decide «cuándo», no «cuánto»
Un error común es confundir el limitador con un semáforo. El semáforo limita el número de operaciones simultáneas y responde a la pregunta «cuántas hay en vuelo ahora». El limitador limita la frecuencia y responde a la pregunta «se puede iniciar otra operación justo ahora y, si no, dentro de cuántos milisegundos se podrá». Ambos mecanismos se complementan, pero no son intercambiables. Se puede mantener una sola conexión y aun así exceder el límite si las solicitudes son cortas. Se pueden mantener cien conexiones y respetar el límite si las solicitudes son lentas.
Tres propiedades de un buen limitador del lado del cliente
- Previsibilidad. Con la misma entrada, da la misma respuesta. Nada de «a veces deja pasar un poco más».
- Bajo costo. La decisión se toma en tiempo constante y con memoria constante por clave. Si tiene miles de hosts, el limitador no puede guardar el historial de todas las solicitudes.
- Equidad. Si varias tareas esperan permiso, lo reciben en orden de llegada, no en orden de «quién se despertó con más suerte».
Tenga en cuenta estos tres criterios: con ellos compararemos los algoritmos en la siguiente sección.
Inmersión profunda: las familias de algoritmos y su matemática
Fixed window: el contador honesto pero traicionero
La versión más simple: dividimos el tiempo en ventanas de longitud fija, en cada ventana llevamos un contador y, al alcanzar la cuota, esperamos al inicio de la siguiente ventana. En memoria: un número y una marca de tiempo por clave. Parecería ideal.
El problema se llama efecto de borde de ventana. Si la cuota es cien solicitudes por minuto, el cliente puede enviar cien solicitudes en el último segundo de una ventana y otras cien en el primer segundo de la siguiente. Desde el punto de vista del cliente, todo es legal: en cada ventana hay exactamente cien. Desde el punto de vista del servidor, en dos segundos llegaron doscientas solicitudes, el doble de cualquier interpretación razonable del límite. Si el servidor cuenta con ventana deslizante (como hacen la mayoría de los modernos), recibirá un rechazo creyéndose inocente.
El segundo mal es la sincronización de ráfagas. Todos sus workers «se despiertan» al mismo tiempo al inicio del minuto, porque es entonces cuando se reinicia el contador. Esto genera picos de carga en la red, en el proxy y en el servidor de destino.
Sliding window log: exacto, pero caro
Guardamos las marcas de tiempo de todas las solicitudes del último intervalo. Antes de enviar, descartamos las vencidas y contamos las restantes. Registro absolutamente exacto, sin efecto de borde. Pero la memoria crece de forma lineal con la cuota: con una cuota de diez mil solicitudes por hora, guarda diez mil marcas por cada clave. Para un host es tolerable; para mil hosts, no.
Sliding window counter: el compromiso
Guardamos dos contadores: el de la ventana actual y el de la anterior. La estimación de la carga es el contador actual más el anterior multiplicado por la fracción de la ventana previa que aún cae dentro del intervalo deslizante. Si transcurrió el 20 por ciento del minuto actual, tomamos el 80 por ciento del contador anterior. Es una aproximación, pero suaviza muy bien el borde y requiere solo dos variables. Muchas implementaciones del lado del servidor usan exactamente esto, así que imitarlo en el cliente es una buena forma de «pensar como el servidor».
Token bucket: el balde de fichas
Imagine un balde con capacidad para B fichas. Cada segundo caen en él r fichas y las sobrantes se desbordan. Para enviar una solicitud de costo c hay que tomar c fichas. Si no las hay, hay que esperar a que se acumulen.
Dos parámetros dan dos propiedades independientes. El parámetro r es la velocidad estable: por mucho que espere, el ritmo de largo plazo no superará r solicitudes por segundo. El parámetro B es la ráfaga máxima: tras un período de inactividad se pueden enviar B solicitudes de inmediato. Esto encaja a la perfección con cómo se formulan las políticas reales del servidor: «no más de cien por minuto, no más de diez a la vez».
El detalle clave de la implementación es la reposición perezosa. No se necesita un hilo de fondo que agregue fichas cada segundo. Basta con que, en cada llamada, se calcule el tiempo transcurrido desde la llamada anterior y se agregue la cantidad correspondiente: tokens = min(B, tokens + elapsed * r). Dos números por clave, cálculo en tiempo constante. Cumple plenamente el criterio de bajo costo.
Leaky bucket: el balde con agujero
Aquí la metáfora se invierte: las solicitudes se vierten en el balde y salen por el agujero del fondo a una velocidad constante r. Si el balde se desborda, la nueva solicitud se rechaza o espera. La salida siempre es pareja: nada de ráfagas, estrictamente una solicitud cada 1/r segundos. Si el servidor no tolera ráfagas o usted quiere el perfil de tráfico más suave posible, esta es su opción.
Existen dos interpretaciones del leaky bucket. La primera es como cola: las solicitudes se guardan realmente en un búfer y un proceso aparte las libera con un temporizador. La segunda es como contador: simplemente verificamos si se desbordaría el balde imaginario y, según eso, dejamos pasar o no. La segunda interpretación se llama en telecomunicaciones GCRA (Generic Cell Rate Algorithm) y es matemáticamente equivalente a token bucket con otra parametrización. Es una observación importante: si ya implementó token bucket, también sabe hacer leaky bucket.
GCRA: una sola marca de tiempo en lugar de un contador
GCRA guarda un único valor: el TAT (theoretical arrival time, tiempo teórico de llegada), el momento antes del cual no debería llegar la siguiente solicitud «ideal». Parámetros: el intervalo de emisión T = 1/r y la tolerancia τ, igual a (B − 1) * T. El algoritmo:
- Obtenemos el tiempo actual now.
- Si TAT es menor que now, consideramos TAT igual a now (el balde está vacío desde hace rato).
- Si TAT − τ es mayor que now, la solicitud llegó demasiado pronto; el tiempo de espera es TAT − τ − now.
- De lo contrario, permitimos la solicitud y adelantamos TAT en T.
Un solo número por clave, sin contadores de punto flotante que se van desviando poco a poco. Por eso GCRA es el algoritmo favorito de los limitadores distribuidos: su estado se guarda fácilmente en un solo campo clave-valor y se actualiza de forma atómica.
Tabla comparativa en palabras
- Fixed window: memoria mínima, precisión baja, ráfagas en los bordes; sirve solo como seguro grueso.
- Sliding log: precisión absoluta, memoria lineal respecto de la cuota; adecuado para pocas claves con cuotas pequeñas.
- Sliding counter: memoria de dos variables, precisión aproximada; imita bien la lógica del servidor.
- Token bucket: memoria de dos variables, control explícito de la ráfaga; estándar para SDK del cliente.
- Leaky bucket / GCRA: memoria de una variable, salida perfectamente pareja; estándar para sistemas distribuidos.
Sobre los relojes: monotonía y deriva
Todos los algoritmos se apoyan en el «tiempo actual». Use relojes monotónicos (monotonic clock), no el reloj del sistema. El reloj del sistema puede saltar hacia atrás al sincronizarse y su limitador creerá que pasó un número negativo de segundos, reiniciará la reposición o, al contrario, emitirá una ráfaga gigantesca. Los relojes monotónicos garantizan que no retroceden. La única excepción es un limitador distribuido en un almacén compartido, donde el tiempo se toma del lado del almacén, no de los clientes, para no depender de las diferencias de reloj entre máquinas.
Método 1: token bucket en la práctica — implementación sin trampas ocultas
Paso 1. Elección de parámetros
Traduzca la política del servidor al par (r, B). Si la documentación dice «cien solicitudes por minuto», la velocidad base es r = 100/60 fichas por segundo. La capacidad B es una decisión aparte. Una elección segura para una API desconocida es B igual al cinco o diez por ciento de la cuota de la ventana, es decir, de cinco a diez fichas con una cuota de cien. Esto permite procesar rápido un lote pequeño, pero no genera picos que el servidor con ventana deslizante interprete como una violación.
Aún mejor: calcular con margen, usando entre el 80 y el 90 por ciento de la velocidad declarada. Los contadores del servidor, las latencias de red y los redondeos en ambos lados introducen inevitablemente una dispersión, y el margen la absorbe.
Paso 2. Estructura del estado
Por cada clave guarde: tokens (número real, cantidad actual de fichas), last (marca monotónica del último recálculo), rate, capacity. Proteja el estado con un mutex o, en código asíncrono, con una única tarea-árbitro por la que pasen todas las solicitudes de fichas.
Paso 3. El algoritmo acquire(cost)
- Tomamos el bloqueo.
- now = monotonic(); elapsed = now − last; last = now.
- tokens = min(capacity, tokens + elapsed * rate).
- Si tokens ≥ cost: tokens −= cost; liberamos el bloqueo; devolvemos «espera cero».
- Si no: wait = (cost − tokens) / rate; descontamos fichas en negativo: tokens −= cost; liberamos el bloqueo; devolvemos wait.
- La parte llamadora duerme wait segundos y luego envía la solicitud.
Fíjese en el punto cinco. Descontar en negativo es una reserva. Garantiza la equidad: la siguiente llamada verá un saldo negativo y obtendrá una espera aún mayor, es decir, se pondrá en cola detrás de la anterior. Sin la reserva aparece el error clásico: diez tareas ven a la vez cero fichas, calculan la misma espera, se despiertan todas juntas y generan una ráfaga que el limitador debía haber evitado.
Paso 4. Límite a la profundidad de la reserva
La reserva en negativo puede crecer sin límite: si las tareas llegan más rápido de lo que se reponen las fichas, la cola de espera crece y el tiempo de espera de la última tiende a horas. Introduzca una demora máxima (max_delay). Si el wait calculado supera el umbral, no reserve y devuelva el error «limitador sobrecargado». Que el planificador de tareas decida qué hacer: posponer, bajar la prioridad, cambiar de host. Este es exactamente el punto en el que el limitador del cliente deja de ser un freno pasivo y se convierte en una herramienta de gestión de la carga.
Paso 5. Costo ponderado
Permita que las solicitudes tengan distinto cost. Los endpoints de búsqueda, las selecciones masivas y las operaciones de escritura suelen ser «más caros» para el servidor, y muchas API lo reflejan en sus políticas. Si la documentación no dice nada, asigne el peso según sus propias observaciones del tiempo de respuesta: una solicitud que el servidor tarda más en procesar es razonable considerarla más costosa. La fórmula de la espera no cambia por ello: el cost simplemente entra como factor.
Paso 6. Calentamiento y arranque en frío
El valor inicial de tokens es una decisión aparte. Un balde lleno al arrancar significa una ráfaga instantánea de B solicitudes en cuanto el proceso inicia. Esto puede ser indeseable si decenas de procesos arrancan a la vez tras un despliegue. Es más seguro empezar en cero o con la mitad de la capacidad. Y si sabe que el servidor cuenta la cuota por una ventana que no está alineada con su arranque, el arranque en cero es además más honesto.
Lista de verificación de token bucket
- Se usan relojes monotónicos.
- La reposición es perezosa, por diferencia de tiempo, sin temporizadores de fondo.
- Hay reserva en negativo para una cola equitativa.
- Existe max_delay y un rechazo explícito cuando se desborda.
- La velocidad se define con margen respecto de la del servidor.
- La capacidad se limita a una fracción razonable de la cuota de la ventana.
- Se admite cost para solicitudes ponderadas.
- El estado inicial no genera ráfaga al desplegar.
Método 2: leaky bucket y GCRA — cuando se necesita un flujo parejo
Cuándo preferir leaky bucket
Token bucket permite ráfagas. Es cómodo, pero hay situaciones en las que la ráfaga es dañina en sí misma: el servidor reacciona con agresividad a los picos breves, el canal del proxy tiene ancho de banda limitado, usted quiere que el patrón de tráfico se parezca al de un cliente común y pausado. En todos estos casos se necesita una salida con un intervalo estrictamente constante entre solicitudes. Eso es el leaky bucket.
Implementación como cola
La variante clásica: un búfer de capacidad fija y un único consumidor que cada T segundos extrae un elemento y lo envía. La ventaja es la simplicidad y lo visual. Las desventajas: hace falta un hilo o una tarea aparte, y si el consumidor se detiene, el búfer «se congela». Este enfoque es adecuado cuando ya tiene una tubería explícita: una cola de tareas de la que las solicitudes se toman de a una.
Implementación como GCRA
Para la mayoría de los escenarios del cliente resulta más cómoda la interpretación contadora. Ya describimos el algoritmo; veamos cómo definir los parámetros. Si se requiere un intervalo estricto, ponga τ = 0: entonces la tolerancia es nula y las solicitudes pasan no más seguido que cada T. Si quiere permitir una pequeña ráfaga, aumente τ. Así, una sola implementación cubre tanto el leaky bucket estricto como el token bucket. Por eso GCRA es un buen «motor único» para una biblioteca de limitación.
Procedimiento paso a paso de GCRA con reserva
- Leer el TAT de la clave; si no existe, considerar TAT = now.
- new_TAT = max(TAT, now) + T * cost.
- allow_at = new_TAT − τ − T * cost; es el momento en que una solicitud de este costo podría haberse enviado sin esperar.
- Si allow_at ≤ now: escribir new_TAT y devolver «espera cero».
- Si no: wait = allow_at − now; si wait supera max_delay, devolver rechazo sin escribir; en caso contrario, escribir new_TAT y devolver wait.
En un almacén distribuido, los pasos del uno al cinco se ejecutan en una sola operación atómica —por ejemplo, un script del lado del almacén—. Así se garantiza que dos clientes no lean el mismo TAT y «dupliquen» el permiso.
Equivalencia y elección según el tipo de carga
Vale la pena entenderlo: token bucket con parámetros (r, B) y GCRA con parámetros (T = 1/r, τ = (B − 1)/r) dejan pasar exactamente las mismas secuencias de solicitudes. La diferencia está solo en la representación del estado. Por eso la pregunta «cuál es mejor» en realidad se plantea de otra forma: ¿necesita ráfaga? Si la necesita, ponga B mayor que uno. Si no, ponga B = 1 (τ = 0). El resto es cuestión de gusto y de comodidad de almacenamiento.
Lista de verificación de leaky bucket / GCRA
- Está decidido si se necesita ráfaga o un flujo estrictamente parejo.
- El estado es un solo valor TAT por clave.
- La operación de lectura-verificación-escritura es atómica.
- Existe max_delay y un rechazo explícito.
- En la variante distribuida, el tiempo se toma del lado del almacén.
Método 3: límites por host — registro, jerarquía y composición
Por qué «un solo limitador para todo» no funciona
Si su cliente consulta una sola API, basta con un balde. Pero los agregadores, los scrapers y los buses de integración se comunican con decenas y cientos de hosts, cada uno con su propia política. Un límite global único o desaprovecha los hosts rápidos o sobrecarga los lentos. Hace falta un registro de limitadores: una asignación «clave de límite — estado del balde», donde la clave se construye a partir de las características de la solicitud.
Clave de límite: del host al endpoint
La clave mínima es esquema más host más puerto. Dos dominios del mismo dueño suelen compartir cuota, y los subdominios pueden contarse por separado; esto hay que saberlo por la documentación o averiguarlo con observación. Una clave más fina es host más patrón de ruta: por ejemplo, el endpoint de búsqueda y el endpoint de la ficha de producto tienen cuotas distintas. Aún más fina: host más token de autorización, si el servidor cuenta la cuota por clave de API y usted tiene varias.
Regla práctica: construya la clave con los mismos criterios con los que cuenta el servidor. Si el servidor cuenta por IP, la clave incluye su IP de salida. Si cuenta por token, el token. Si cuenta por ambos a la vez, usted necesita dos limitadores y la solicitud debe pasar por los dos.
Jerarquía de límites
Un sistema bien diseñado ordena los limitadores por niveles:
- Global: el presupuesto total del proceso. Protege sus propios recursos: sockets, memoria, ancho de banda del canal.
- Por IP de salida: cuántas solicitudes salen por una dirección concreta. Nivel clave cuando se trabaja con un grupo de direcciones.
- Por host: la política del servidor de destino en su conjunto.
- Por endpoint: cuotas separadas para los métodos costosos.
- Por credenciales: cuotas por token o cuenta.
La solicitud debe obtener permiso en todos los niveles. Esto es la composición de limitadores.
Composición sin bloqueos mutuos
El enfoque ingenuo es llamar a acquire de cada limitador en secuencia y sumar las esperas. Es incorrecto: el primer limitador ya descontó una ficha, y el segundo obliga a esperar diez segundos, durante los cuales la ficha del primero «vence» desde el punto de vista de la equidad. Peor aún, dos tareas que toman los limitadores en distinto orden pueden estorbarse indefinidamente.
El procedimiento correcto:
- Para cada limitador, calcular la espera sin descontar (operación peek).
- Tomar el máximo de las esperas: ese es el wait total.
- Si wait supera max_delay, rechazar.
- En caso contrario, descontar en todos los limitadores, pasándoles un tiempo de llegada único now + wait, para que cada uno reserve el recurso para el mismo momento.
- Dormir wait y enviar.
Recorra siempre los limitadores en el mismo orden fijo (por ejemplo, del global al más específico). Esto evita bloqueos mutuos en el acceso concurrente.
Configuración y valores por defecto
El registro debe poder crear un limitador para un host que no se ha visto antes. Defina un valor por defecto conservador: velocidad baja, ráfaga mínima. Para los hosts conocidos, una configuración explícita. Una buena práctica es guardar la política de forma declarativa: host o patrón, rate, burst, cost por patrones de ruta, marca de «contar por IP» y «contar por token». Así, cuando cambia la política del servidor, se modifica un solo archivo y no el código.
Desalojo y fugas
Un registro con miles de hosts es candidato a fuga de memoria. Los hosts a los que hace mucho no se accede deben desalojarse. Como el estado del balde tras un largo período de inactividad será «lleno» de todos modos (o el TAT estará en el pasado), el desalojo no pierde información: en el siguiente acceso el limitador se creará de nuevo en el mismo estado. Use una caché LRU con tamaño limitado o una limpieza periódica de las entradas cuyo last sea más antiguo que varias ventanas.
Lista de verificación de límites por host
- La clave de límite repite los criterios con los que cuenta el servidor.
- Existen los niveles: global, IP, host, endpoint, credenciales.
- La composición es mediante peek — máximo — descuento único.
- Los limitadores se recorren en un orden fijo.
- Hay valores por defecto conservadores para hosts desconocidos.
- Las políticas están fuera del código, en configuración.
- El registro tiene tamaño limitado y desaloja las claves inactivas.
Método 4: el limitador y la rotación de IP — cómo contemplar el cambio de dirección en el modelo
Por qué la rotación rompe un limitador ingenuo
Si el servidor de destino cuenta la cuota por IP, el cambio de dirección cambia la clave de límite del lado del servidor. Un cliente ingenuo que lleva un solo contador por host seguirá frenando tras el cambio de IP, aunque el servidor ya vea a un «nuevo» visitante. El error inverso es más peligroso: el cliente reinicia todos los límites al cambiar de IP, incluidos los que el servidor cuenta por token o cuenta, y recibe un rechazo por una cuota que no tiene nada que ver con la IP. Conclusión: la rotación debe afectar solo al nivel «por IP de salida» de la jerarquía, y los demás niveles deben vivir su propia vida.
Dos modos de cambio de dirección
En la infraestructura de Proxeon, la IP del puerto cambia por temporizador o por enlace/API (según datos al 22.09.2026). Son dos escenarios fundamentalmente distintos para el limitador. Con el cambio por temporizador, el cliente no controla el momento: la dirección cambia «desde fuera», y el limitador por IP debe enterarse —mediante un evento, consultando la dirección actual o por un calendario si se conoce el intervalo—. Con el cambio por enlace, el cliente inicia él mismo el cambio y puede sincronizarlo con su propio estado: esperar a que terminen las solicitudes en vuelo, fijar el momento y crear una nueva clave «host más época de IP».
¿Qué tan común es cada modo? Según datos al 14.11.2026, la proporción de cambios de IP por temporizador es del 51,1 %, y el resto corresponde a enlace/API. Es decir, ambas estrategias se dan más o menos por igual, y un limitador universal debe soportar las dos.
La época de la dirección como parte de la clave
En lugar de guardar en la clave la IP misma (que además puede no conocerse de antemano), use una época: un contador que se incrementa con cada cambio. La clave del nivel «por IP» pasa a ser el par «puerto más época». Al cambiar la época, la clave antigua simplemente deja de usarse y más tarde la desaloja el registro, y la nueva se crea en estado inicial. Fíjese: el estado inicial debe ser de nuevo conservador. La nueva dirección es, para el servidor, un desconocido, y lo primero que verá es su patrón de tráfico.
Alinear la ventana del limitador con el temporizador de rotación
Según datos al 14.11.2026, el intervalo mediano entre cambios de IP por temporizador es de 120 s, y el 78,1 % de los intervalos por temporizador son múltiplos exactos de un minuto. Esto es muy cómodo para el diseño. Si usted tiene la cuota por host «N solicitudes por minuto por IP», y la dirección vive dos minutos, el presupuesto de una dirección es exactamente dos ventanas de un minuto. El limitador por IP puede funcionar como token bucket con velocidad N/60 y capacidad calculada para no superar 2N durante la vida de la dirección. Lo importante es no «recuperar» lo perdido: si en el primer minuto envió poco, en el segundo no puede enviar el doble, porque el servidor cuenta por ventana de un minuto, no por su época.
Pausa durante el cambio
El cambio de dirección no es instantáneo. Según datos al 14.11.2026, la duración media del cambio en sí —desde la orden hasta la nueva dirección— es de 4,56 s, y el 80,8 % de los cambios se completan en 5 segundos. ¿Qué significa esto para el limitador? Durante el cambio, las solicitudes o saldrán por la dirección antigua o no saldrán en absoluto. La estrategia correcta es tratar el cambio como un breve intervalo de «drenaje»: antes de la orden de cambio, el limitador deja de emitir nuevos permisos, espera a que terminen las solicitudes en vuelo, ejecuta el cambio y luego abre una nueva época. Como cuatro de cada cinco cambios se completan en cinco segundos o menos, es razonable fijar para la espera de la nueva dirección un tiempo límite algo superior a esa marca y pasar al manejo de la excepción si se supera.
Limite la frecuencia de la propia orden de cambio
Aquí hay un dato que a menudo se pasa por alto: la orden de cambio de IP también es una solicitud a la API, y también hay que limitarla. Según datos al 14.11.2026, la proporción de registros duplicados de cambios por enlace (intervalo no mayor a 2 s, la misma IP) es del 1,2 %. Son huellas de situaciones en las que el cliente pulsó el enlace dos veces seguidas: por una carrera entre workers, por un reintento por timeout, por la falta de un punto único de decisión. La solución es un balde aparte con capacidad uno y un intervalo estricto (leaky bucket puro con τ = 0) para la orden de rotación, más deduplicación: si el cambio ya está en marcha, los demás workers esperan su resultado en lugar de iniciar otro. El mismo principio que para los hosts de destino, aplicado a su propia infraestructura.
Escala y planificación del presupuesto
Para dimensionar la magnitud: según datos al 14.11.2026, en un día se realizaron 2 196 242 cambios de IP en toda la red de Proxeon, participaron 7 924 puertos proxy, y la mediana de IP únicas por módem en un día es de 95. Para el diseñador del limitador esto significa que un puerto pasa por decenas de épocas de dirección al día, y el estado «por IP» debe ser liviano y de desalojo rápido: no tiene ningún sentido guardar el historial de todas las épocas, pero sí es obligatorio garantizar un costo constante de creación de una nueva época.
Protocolos y direccionamiento de puertos
Un detalle menor que simplifica la configuración: en Proxeon, el puerto SOCKS5 es igual al puerto HTTP más uno (según datos al 22.09.2026). Si usa ambos protocolos para un mismo canal, el limitador por IP debe contarlos como una sola clave y no como dos: la dirección es compartida, así que el presupuesto también. Anote en el registro la normalización: la clave se construye por el puerto HTTP, y el puerto SOCKS5 se reduce a él restando uno.
Limitador distribuido por IP
Cuando por un mismo puerto pasan varios procesos o máquinas, el balde debe ser compartido. Use un almacén con operaciones atómicas, guarde el TAT (GCRA) bajo la clave «puerto más época más host», actualice con un script del lado del almacén y tome el tiempo de allí mismo. Guarde también la época de forma centralizada y cámbiela de forma atómica junto con la orden de rotación; así todos los procesos pasan de forma coordinada a la nueva clave.
Lista de verificación del limitador ante la rotación
- La rotación afecta solo al nivel «por IP»; los demás niveles no se reinician.
- Se soportan ambos modos: temporizador y cambio por enlace/API.
- La clave del nivel IP incluye la época de la dirección.
- La nueva época arranca en estado conservador.
- La velocidad por IP está alineada con la ventana del servidor, no con la duración de la época.
- Durante el cambio se suspende la emisión de permisos.
- La orden de rotación se limita a sí misma y se deduplica.
- Los puertos HTTP y SOCKS5 de un mismo canal se normalizan en una sola clave.
- Para escenarios multiproceso, el estado se lleva a un almacén compartido.
Errores típicos de diseño del rate limit del lado del cliente
Error 1. Sleep en lugar de un limitador
«Pongamos una pausa de cien milisegundos entre solicitudes» es la solución más frecuente y la más frágil. No tiene en cuenta el tiempo de la propia solicitud, no funciona con varios workers, no permite ráfagas donde están permitidas y no protege de que aparezcan donde están prohibidas. Una pausa no es un limitador, es una imitación.
Error 2. Contar por ventana cuando el servidor cuenta de forma deslizante
El efecto de borde de ventana se explicó antes. Si no está seguro de cómo cuenta el servidor, suponga lo peor —una ventana deslizante— y use token bucket con una capacidad modesta.
Error 3. Carrera sin reserva
Varias tareas calculan a la vez la misma espera, se duermen y se despiertan juntas. El resultado es justamente la ráfaga que el limitador debía evitar. Se cura con la reserva (descanso en negativo o desplazamiento del TAT) bajo bloqueo.
Error 4. Cola de espera infinita
Sin max_delay, la cola crece sin control y las tareas esperan minutos y horas, consumiendo memoria y conexiones. El limitador debe saber rechazar.
Error 5. Reloj del sistema
Un solo salto de tiempo al sincronizar y el balde se desborda o se «congela». Solo relojes monotónicos en el cliente; solo el tiempo del almacén en la variante distribuida.
Error 6. Reiniciar todos los límites al cambiar de IP
Las cuotas por token y por cuenta no dependen de la dirección. Si las reinicia, al instante violará una política que no le concernía.
Error 7. Balde lleno al arrancar
Decenas de procesos tras un despliegue arrancan con baldes llenos y emiten una ráfaga simultánea. Empiece con el balde vacío o agregue una demora aleatoria al arranque.
Error 8. Registro sin desalojo
Cada nuevo host es una entrada para siempre. Tras semanas de operación, el proceso guarda en memoria limitadores de hosts que nunca volverá a necesitar.
Error 9. Ignorar el costo de la solicitud
Si el servidor cuenta una búsqueda como diez unidades y usted como una, su limitador dejará pasar diez veces más de lo necesario y se sorprenderá sinceramente ante el rechazo.
Error 10. Orden de rotación sin límite
La repetición de la orden de cambio de dirección por timeout o desde varios workers produce duplicados y cambios de más. La orden también es un recurso: déle su propio balde.
Herramientas y recursos para la implementación
Bibliotecas listas por ecosistema
- Go: el paquete golang.org/x/time/rate es la implementación de referencia de token bucket, con métodos Allow, Reserve y Wait. El método Reserve devuelve un objeto con el tiempo de espera y la posibilidad de cancelación, justo lo que se necesita para la composición.
- Python: la biblioteca limits ofrece fixed window, sliding window y GCRA con distintos backends; aiolimiter implementa leaky bucket para asyncio; pyrate-limiter soporta varias ventanas a la vez.
- Java/Kotlin: Bucket4j es un token bucket maduro con soporte para almacenes distribuidos; Resilience4j RateLimiter es la variante con ciclos fijos de renovación.
- JavaScript/TypeScript: bottleneck sabe limitar por grupos de claves y agruparse en clúster mediante un almacén compartido; p-throttle es la variante minimalista para casos simples.
- Rust: governor es una implementación de GCRA con y sin claves, apta para código asíncrono.
- .NET: el espacio integrado System.Threading.RateLimiting incluye token bucket, sliding window y limitadores por partición según la clave.
Almacenes para el estado distribuido
Redis y los almacenes compatibles con scripts del lado del servidor son el estándar para un GCRA compartido: una sola operación atómica, el tiempo se toma con un comando del almacén, las claves con TTL se desalojan automáticamente. Para escenarios dentro de un solo clúster de aplicaciones también sirven mecanismos integrados como las cachés distribuidas con operaciones atómicas.
Herramientas de observabilidad
Un limitador sin métricas es una caja negra. Exporte: el número de permisos sin espera, la distribución del tiempo de espera, el número de rechazos por max_delay, el llenado actual de los baldes por clave y la frecuencia de cambio de épocas de dirección. Un histograma de espera por host mostrará de inmediato dónde la política es demasiado estricta y dónde está al borde.
Infraestructura de direcciones
Para escenarios con rotación hará falta un proveedor que ofrezca dos modos de cambio de dirección —por temporizador y por enlace/API— y un direccionamiento de puertos predecible. En Proxeon ambos modos están disponibles, y el puerto SOCKS5 dista exactamente uno del puerto HTTP (según datos al 22.09.2026), lo que simplifica la normalización de claves en el registro de limitadores.
Qué leer
- La descripción de GCRA en las especificaciones de estándares de telecomunicaciones: la fuente original del leaky bucket como contador.
- La documentación del paquete x/time/rate: la formulación ejemplar de la semántica de Reserve y Wait.
- Las secciones sobre límites en la documentación de las grandes API públicas: allí aparecen todos los modelos de conteo, y es la mejor forma de aprender a traducir una política a los parámetros del balde.
Casos y escenarios de aplicación
Escenario 1. Agregador de precios con cientos de hosts
Tarea: recorrer periódicamente fichas de producto en muchas plataformas, cada una con su propia política. Solución: un registro de limitadores con clave «host más patrón de ruta», un valor por defecto conservador para las plataformas nuevas y políticas explícitas para las conocidas. Composición con un límite global por número de sockets. Resultado al que aspiran estos sistemas: carga uniforme de todos los hosts, sin tiempo ocioso en los rápidos y sin sobrecarga en los lentos; cuando cambia la política de una plataforma, se modifica una línea de configuración. La lección principal: pasar de un límite global único a una jerarquía reduce drásticamente la proporción de solicitudes enviadas «en vano».
Escenario 2. SDK para una API asociada con cuota por token y por IP
Tarea: una biblioteca para clientes que tienen varios tokens y varias direcciones de salida. Solución: dos niveles de limitadores —por token y por dirección— con composición mediante peek y un tiempo de llegada único. El planificador elige el par «token más dirección» con la menor espera. Lección: el limitador se convierte en una herramienta de enrutamiento: en lugar de «esperar», sugiere «a dónde enviar para no esperar».
Escenario 3. Scraper con direcciones móviles y rotación por temporizador
Tarea: recorrer páginas abiertas mediante un grupo de puertos, con direcciones que cambian por temporizador. Solución: un limitador por IP con clave «puerto más época», velocidad alineada con la ventana de un minuto del host de destino. Teniendo en cuenta que, según datos al 14.11.2026, el intervalo mediano por temporizador es de 120 s y el 78,1 % de los intervalos son múltiplos de un minuto, el presupuesto por época se calcula como un número entero de ventanas de un minuto. Durante el cambio —y el 80,8 % de los cambios se completan en 5 segundos (según datos al 14.11.2026)— la emisión de permisos se pone en pausa con un tiempo límite algo superior a ese umbral. Lección: alinear la ventana del limitador con el ritmo de rotación evita las ráfagas «de recuperación» al inicio de una nueva época.
Escenario 4. Workers con rotación por enlace y órdenes duplicadas
Tarea: varios workers comparten un puerto y cada uno inicia un cambio de dirección cuando lo necesita. Síntoma: huellas de órdenes repetidas en los registros. Solución: un único punto de rotación con leaky bucket (τ = 0) y deduplicación: si el cambio ya está en marcha, los demás esperan a que termine. Según datos al 14.11.2026, la proporción de registros duplicados de cambios por enlace en la red es del 1,2 %; son exactamente las situaciones que elimina un único punto de decisión. Lección: hay que limitar no solo las solicitudes a las API ajenas, sino también las órdenes a la propia infraestructura.
Escenario 5. Un motor único sobre GCRA para todos los niveles
Tarea: simplificar una base de código donde históricamente convivían fixed window, pausas con sleep y contadores manuales. Solución: una única implementación de GCRA con parámetros (T, τ), aplicada en todos los niveles de la jerarquía, con el estado en un almacén compartido para las claves distribuidas y en memoria para las locales. Lección: una sola fórmula reemplaza un zoológico de soluciones y hace previsible el comportamiento del sistema.
FAQ: respuestas a preguntas difíciles
¿En qué se diferencia en esencia token bucket de leaky bucket, si son equivalentes?
Son equivalentes como objetos matemáticos: con la correspondencia correcta de parámetros, dejan pasar exactamente las mismas secuencias. La diferencia está en la intuición y en cuál parámetro controla usted directamente. Token bucket piensa en términos de «velocidad y ráfaga»; leaky bucket, en términos de «intervalo y tolerancia». Para políticas del tipo «N por minuto, no más de M a la vez», el primero es más cómodo; para «exactamente una solicitud cada T», el segundo. GCRA reúne ambas intuiciones en un solo estado.
¿Cómo elegir la capacidad del balde si el servidor no publica la ráfaga admisible?
Empiece por una fracción pequeña de la cuota de la ventana —del orden del cinco al diez por ciento— y observe. Si no hay rechazos y las esperas son grandes, aumente con cuidado. Recuerde que un servidor con ventana deslizante no tolera ráfagas que superen la cuota en un subintervalo corto, así que la capacidad nunca debe acercarse a la cuota completa.
¿Hace falta un limitador si tengo un solo hilo?
Sí. Un solo hilo con solicitudes cortas excede fácilmente la cuota: si la respuesta llega en veinte milisegundos, enviará cincuenta solicitudes por segundo sin siquiera pensarlo. El limitador hace falta sin importar el número de hilos; resuelve una cuestión distinta de la del semáforo.
¿Cómo limitar solicitudes con distinto costo si el servidor las cuenta de forma distinta?
Pase el cost a acquire. Las fichas se descuentan en proporción y la espera se calcula con la misma fórmula. Si el costo es desconocido, estímelo por el tiempo de respuesta o por el tamaño de la respuesta y afínelo según lo observe. Es mejor sobreestimar que subestimar.
¿Qué hacer si una sola solicitud debe pasar por cinco limitadores y cada uno da una espera distinta?
Primero pregunte a todos la espera sin descontar, tome el máximo y luego descuente en todos para un mismo momento de llegada. Recorra los limitadores siempre en el mismo orden. Si el máximo supera el umbral, rechace sin descontar; de lo contrario, los recursos quedarán reservados «en vano».
¿Cómo debe reaccionar el limitador ante un cambio de IP por temporizador si no conozco el momento exacto?
Use un evento o la consulta de la dirección actual y, si conoce el intervalo, un calendario con margen. En Proxeon, el cambio por temporizador y el cambio por enlace/API son ambos modos estándar (según datos al 22.09.2026), y si necesita una sincronización exacta, es preferible el modo por enlace: así usted determina el momento del cambio y abre una nueva época en su registro justo cuando el cambio está confirmado.
¿Por qué no se pueden reiniciar todos los límites tras el cambio de dirección?
Porque el servidor puede contar la cuota por varios criterios a la vez. La dirección cambió: la cuota por IP empieza de nuevo, pero la cuota por token, cuenta o sesión sigue contando. Si reinicia todo, violará las políticas que no dependen de la dirección. La rotación debe afectar solo al nivel «por IP» de la jerarquía.
¿Qué es mejor para un limitador distribuido: token bucket o GCRA?
GCRA. Tiene un solo valor de estado, es más fácil de actualizar de forma atómica y más fácil de guardar con TTL. Token bucket requiere dos valores y una lógica de reposición algo más compleja, lo que complica el script atómico. Semánticamente ambos dan el mismo resultado.
¿Cómo comprobar que el limitador funciona bien antes de pasar a producción?
Escriba una prueba con relojes sustituibles: entregue solicitudes en momentos dados y compare las decisiones con una secuencia de referencia. Verifique los casos límite: tiempo cero, inactividad prolongada, llegada simultánea de muchas solicitudes, costo mayor que la capacidad (debe haber un rechazo explícito, no una espera infinita). Pruebe por separado la composición: dos limitadores con velocidades distintas y la comprobación de que ninguno deja pasar más que su cuota.
Conclusión: qué hacer a continuación
El rate limit del lado del cliente no es un freno, es un sistema de gestión. Un limitador bien construido hace tres cosas: no llega al rechazo, usa de forma uniforme el presupuesto disponible y le sugiere al planificador a dónde y cuándo enviar la siguiente solicitud. En la base hay una sola fórmula, sea token bucket o GCRA, pero hay que rodearla de disciplina: relojes monotónicos, reserva bajo bloqueo, demora máxima, jerarquía de claves y desalojo.
Resumen breve:
- Fixed window es simple pero traicionero en los bordes; prefiera token bucket o GCRA.
- Token bucket da control separado de la velocidad y la ráfaga; GCRA, lo mismo en un solo número de estado.
- La clave de límite repite los criterios con los que cuenta el servidor; los limitadores se ordenan en jerarquía y se componen mediante peek — máximo — descuento único.
- La rotación de dirección cambia solo el nivel «por IP»; la orden de rotación merece su propio balde.
- Las métricas de espera y de rechazos son la única forma honesta de saber en qué medida su política coincide con la del servidor.
Próximos pasos para usted: elija un motor único (recomendamos GCRA), describa en configuración las políticas de los hosts conocidos, agregue un valor por defecto conservador, active las métricas y corra las pruebas con relojes sustituibles. Si trabaja con un grupo de direcciones, agregue la época a la clave y un balde aparte para la orden de cambio. Después de eso, su cliente se verá ante cualquier servidor como el invitado más educado: ese a quien nunca le dicen que no.