Limitación de velocidad de API: 4 algoritmos que todo desarrollador debería conocer
Ventana fija, ventana deslizante, depósito de tokens y depósito con fugas explicados con diagramas, encabezados X-RateLimit y lógica de reintento de Node.js que puede copiar y pegar.
Su trabajo por lotes activa 200 solicitudes en 3 segundos y cada respuesta regresa 429 Too Many Requests.
Su procesador de webhook ataca una API de terceros y se bloquea durante 15 minutos. La integración de un cliente
se queda en silencio porque su ciclo de reintento agota la cuota diaria en la primera hora. Estos fracasos comparten
una causa fundamental: el código no respeta los límites de tarifas.
Esta guía cubre los cuatro algoritmos de limitación de velocidad central y le muestra cómo leer X-RateLimit
encabezados de cualquier API y le proporciona copiar y pegar código Node.js para la lógica de reintento con retroceso exponencial.
Los cuatro algoritmos de limitación de velocidad.
Cada limitador de velocidad responde a la misma pregunta: "¿debería aprobarse esta solicitud o debería rechazarla?" Los cuatro algoritmos difieren en cómo rastrean el tiempo y manejan las ráfagas.
1. Ventana fija
El enfoque más simple. Divida el tiempo en intervalos fijos (por ejemplo, 1 minuto). Cuente las solicitudes por intervalo. Cuando el conteo llegue al límite, rechace todo hasta que comience el siguiente intervalo.
La ventana fija es fácil de construir: un contador y una marca de tiempo por cliente. El inconveniente es el problema de límites. Un cliente puede enviar el límite completo al final de una ventana y el límite completo al comienzo del siguiente, obteniendo el doble de la tasa prevista en una breve ráfaga. API más antigua de GitHub limitador de velocidad utilizado ventanas fijas; Desde entonces, han adoptado enfoques más sofisticados.
2. Ventana corredera
En lugar de restablecerse en límites fijos, la ventana se desliza con cada solicitud. En cualquier momento dado, el limitador revisa los últimos N segundos y cuenta las solicitudes en ese lapso.
La ventana deslizante elimina el problema de explosión de límites. El costo es mayor memoria: almacena una marca de tiempo
para cada solicitud, ni un solo contador. Redis ZRANGEBYSCORE hace que esto sea práctico a escala.
Cloudflare y muchas puertas de enlace API utilizan ventanas deslizantes para límites de tarifas por usuario.
3. Cubo de fichas
Imagínese un cubo que contiene fichas. Cada solicitud cuesta una ficha. Recarga de tokens a una tarifa fija. Si el depósito está vacío, la solicitud se rechaza. Si el cubo está lleno, las fichas sobrantes no se acumulan.
El depósito de tokens es el algoritmo más popular en producción. Stripe, AWS API Gateway y la mayoría de las nubes los proveedores utilizan variantes del mismo. La capacidad del cucharón controla el tamaño de ráfaga y la tasa de recarga controla rendimiento sostenido. Dos parámetros le brindan un control detallado sobre la forma del tráfico.
4. Balde con fugas
Lo inverso del depósito de fichas. Las solicitudes llenan un balde. El balde drena a un ritmo constante. si el El depósito se desborda y el exceso de solicitudes se rechaza. La tasa de producción se mantiene constante independientemente de la entrada. ráfagas.
El cubo con fugas funciona bien para dar forma al tráfico donde se necesita una tasa de salida constante: trabajadores en cola, entrega de webhooks y canalizaciones de codificación de vídeo. La desventaja es que las ráfagas se ponen en cola en lugar de que servido; La latencia aumenta bajo carga.
Comparando los cuatro algoritmos
| Algoritmo | ¿Se permite estallar? | Memoria | Caso de uso común |
|---|---|---|---|
| ventana fija | Explosiones de borde (2x en el límite) | Bajo (1 contador) | Contadores simples, análisis. |
| ventana corredera | Suave, sin picos en los límites | Medio (marca de tiempo por solicitud) | Límites de API por usuario |
| Cubo de fichas | Ráfagas controladas hasta su capacidad | Bajo (2 valores) | La mayoría de las API de producción (Stripe, AWS) |
| balde con fugas | Tasa de salida constante y en cola | Medio (cola) | Conformación del tráfico, trabajadores en cola |
Lectura de encabezados X-RateLimit
La mayoría de las API incluyen información sobre el límite de velocidad en los encabezados de respuesta. Tres encabezados te lo dicen todo debes mantenerte por debajo del límite:
X-RateLimit-Limit: solicitudes máximas permitidas por ventanaX-RateLimit-Remaining: solicitudes que has dejado en la ventana actualX-RateLimit-Reset: Marca de tiempo Unix (segundos) cuando la ventana se reinicia
Cuando se excede el límite, el estado de respuesta es 429 Too Many Requests y el
Retry-After El encabezado le indica cuántos segundos esperar.
Pruébelo con la API de botoi. Este comando curl codifica una cadena e imprime los encabezados del límite de velocidad:
Encabezados de respuesta:
Esto le indica que el límite es 5 solicitudes por ventana, le quedan 4 después de esta solicitud y el La ventana se restablece en la marca de tiempo Unix dada. Realice un seguimiento de estos valores en su cliente HTTP para evitar golpear 429 en primer lugar.
Consejo: Convertir X-RateLimit-Reset a un tiempo de espera:
waitMs = (resetTimestamp - Math.floor(Date.now() / 1000)) * 1000
Reintentar la lógica con retroceso exponencial en Node.js
Cuando llegue un 429, no lo vuelvas a intentar inmediatamente. Un ciclo de reintento estrecho empeora el problema: te quedas la velocidad está limitada por más tiempo y el servidor lo marca como abusivo. En su lugar, utilice un retroceso exponencial con fluctuación.
Úselo con cualquier punto final:
La función busca una Retry-After encabezado primero. Si el servidor te dice cuanto tiempo
esperar, respetarlo. Si no existe ningún encabezado, vuelve al retroceso exponencial: 1 segundo, 2 segundos,
4 segundos, 8 segundos. La fluctuación aleatoria (0-500 ms) evita el atronador problema del rebaño donde cientos de
los clientes vuelven a intentarlo exactamente en el mismo momento.
Aceleración proactiva: evite los 429 antes de que sucedan
El reintento reactivo maneja los errores después de que ocurren. La limitación proactiva los previene. si lo sabes el límite de velocidad (de documentos o encabezados), controle sus solicitudes en el lado del cliente.
Este limitador de velocidad del lado del cliente rastrea las marcas de tiempo de las solicitudes en una ventana deslizante. Antes de cada solicitud, comprueba si la ventana está llena y espera si es necesario. Envías solicitudes con la máxima seguridad. tarifa sin un solo 429.
El modelo de limitación de tasas de Botoi
Botoi utiliza un sistema de limitación de tarifas de dos niveles:
| Plan | Ráfaga (por minuto) | Cuota | autenticación |
|---|---|---|---|
| Gratis ($0) | 5 solicitudes/min | 100/día | Ninguno (basado en IP) |
| Inicial ($9/mes) | 30 solicitudes/min | 300.000/mes | clave API |
| Profesional ($49/mes) | 300 solicitudes/min | 3.000.000/mes | clave API |
| Empresa ($199/mes) | 1.000 solicitudes/min | 30.000.000/mes | clave API |
El acceso anónimo rastrea las solicitudes por dirección IP. El recuento diario se reinicia a la medianoche UTC mediante un Contador Cloudflare KV. Las solicitudes autenticadas utilizan la clave API para identificación y límites. se aplican a través de de Unkey limitador de tasa de depósito de tokens en el borde.
Cada respuesta de api.botoi.com incluye los tres X-RateLimit encabezados
descrito anteriormente, por lo que su lógica de reintento funciona de la misma manera independientemente del plan.
Enfoques probados para consumidores de API
- Lea los encabezados de cada respuesta. No codifique los límites de tarifas de la documentación. Las API cambian los límites sin previo aviso. Los encabezados son la fuente de la verdad.
- Utilice un retroceso exponencial con fluctuación. Los intervalos de reintento fijos causan sincronización reintentos entre clientes. La inquietud distribuye la carga.
- Lote donde la API lo admite. Una solicitud con 10 artículos cuesta 1 límite de tarifa ficha. Diez solicitudes individuales cuestan 10.
- Respuestas en caché. Si los datos no cambian entre solicitudes, almacene el resultado y omita la llamada API. Los registros DNS, los certificados SSL y los datos WHOIS rara vez cambian en cuestión de minutos.
- Utilice una cola para el trabajo en segundo plano. No active llamadas API desde un bucle activo. empujar trabaje en una cola (BullMQ, SQS, Cloudflare Queues) y procese elementos a un ritmo controlado.
-
Controle su cuota restante. Registro
X-RateLimit-Remaininga tu panel de métricas. Establezca una alerta cuando caiga por debajo del 20% del límite.
Puntos clave
- Dominan cuatro algoritmos. La ventana fija es la más sencilla. El depósito de tokens es el más popular. La ventana deslizante elimina las ráfagas de límites. El cucharón con fugas suaviza la producción.
-
Los encabezados X-RateLimit son su API. Leer
Limit,Remaining, yReseten cada respuesta para mantenerse por debajo del límite. -
Retroceso exponencial con jitter maneja 429s. Copia el
fetchWithRetryfunción anterior en su base de código y envuelva cada llamada API externa. - La aceleración proactiva evita los 429. Controle sus solicitudes del lado del cliente en lugar de esperar a que el servidor retroceda.
- No se requiere cuenta para realizar la prueba. Acceda a cualquier punto final de botoi en api.botoi.com con 5 solicitudes gratuitas por minuto para ver los encabezados de límite de tarifas en acción.
FAQ
- ¿Qué es la limitación de la tasa de API y por qué la utilizan las API?
- La limitación de tarifas limita la cantidad de solicitudes que un cliente puede realizar en un período de tiempo. Las API lo utilizan para proteger los servidores contra sobrecargas, evitar abusos, garantizar un intercambio justo de recursos entre los clientes y mantener los costos de infraestructura predecibles. Sin él, un solo cliente podría matar de hambre a todos los demás.
- ¿Qué significan los encabezados X-RateLimit?
- X-RateLimit-Limit son las solicitudes máximas permitidas por ventana. X-RateLimit-Remaining es cuántos te quedan. X-RateLimit-Reset es una marca de tiempo de Unix cuando se reinicia la ventana. Reintentar después (en 429 respuestas) le indica cuántos segundos debe esperar antes de volver a intentarlo.
- ¿Cómo debo manejar una respuesta 429 Demasiadas solicitudes?
- Lea el encabezado Retry-After y espere tantos segundos. Si no existe ningún encabezado Retry-After, utilice un retroceso exponencial: espere 1 segundo después del primer 429, 2 segundos después del segundo, 4 después del tercero, y así sucesivamente. Agregue jitter aleatorio (0-500 ms) para evitar problemas de rebaño cuando muchos clientes reintentan al mismo tiempo.
- ¿Qué algoritmo de limitación de velocidad es el más común?
- El depósito de tokens es el más común en las API de producción. Stripe, AWS y la mayoría de los proveedores de la nube utilizan variantes del mismo. El depósito de tokens permite ráfagas controladas al tiempo que aplica una tasa sostenida, que coincide mejor con los patrones de tráfico reales que las ventanas fijas.
- ¿La tasa de botoi limita las solicitudes anónimas?
- Sí. Las solicitudes anónimas (sin clave API) obtienen 5 solicitudes por minuto y 100 solicitudes por día, rastreadas por dirección IP. Las solicitudes autenticadas en planes pagos obtienen límites más altos: Starter permite 30/min, Pro permite 300/min y Business permite 1000/min.
Empieza a construir con botoi
150+ endpoints de API para consultas, procesamiento de texto, generacion de imagenes y utilidades para desarrolladores. Plan gratuito, sin tarjeta de credito.