📖 Documentación para Usuarios

Esta guía está dirigida a administradores del sistema. Si eres desarrollador y buscas información sobre cómo usar la API con rate limiting, consulta la Guía de Rate Limiting para Usuarios.

Variables de Entorno

.env 
# Límites individuales por usuario/IP
RATE_LIMIT_DEFAULT=200 per hour      # Límite por usuario/hora
RATE_LIMIT_BURST=50 per minute       # Límite por usuario/minuto

# Límites globales para toda la aplicación
RATE_LIMIT_GLOBAL=5000 per hour      # Límite total/hora para todos los usuarios
RATE_LIMIT_GLOBAL_BURST=1000 per minute  # Límite total/minuto para todos los usuarios

# Almacenamiento (usar Redis en producción)
RATE_LIMIT_STORAGE_URI=memory://     # Desarrollo: memory://
                                     # Producción: redis://localhost:6379

Cómo Ajustar los Límites

Para Desarrollo

Los valores por defecto son apropiados para testing:

  • Individuales: 200/hora, 50/min
  • Globales: 5000/hora, 1000/min

Para Producción - Servidor Pequeño (2 CPUs, 4GB RAM)

Configuración Recomendada

.env 
RATE_LIMIT_DEFAULT=100 per hour
RATE_LIMIT_BURST=25 per minute
RATE_LIMIT_GLOBAL=2000 per hour
RATE_LIMIT_GLOBAL_BURST=400 per minute

Para Producción - Servidor Mediano (4 CPUs, 8GB RAM)

Configuración Recomendada

.env 
RATE_LIMIT_DEFAULT=200 per hour
RATE_LIMIT_BURST=50 per minute
RATE_LIMIT_GLOBAL=5000 per hour
RATE_LIMIT_GLOBAL_BURST=1000 per minute

Para Producción - Servidor Grande (8+ CPUs, 16GB+ RAM)

Configuración Recomendada

.env 
RATE_LIMIT_DEFAULT=500 per hour
RATE_LIMIT_BURST=100 per minute
RATE_LIMIT_GLOBAL=15000 per hour
RATE_LIMIT_GLOBAL_BURST=3000 per minute

Guía de Dimensionamiento

Calcular Límite Global Apropiado

  1. Determina el número de usuarios concurrentes esperados

    Ejemplo: 50 usuarios activos simultáneamente

  2. Multiplica por su uso promedio

    Ejemplo: 50 usuarios × 50 peticiones/min = 2500 pet/min

  3. Añade margen de seguridad (20-30%)

    Ejemplo: 2500 × 1.3 = 3250 pet/min

  4. Ajusta según capacidad del servidor
    • Monitorea CPU, memoria y latencia
    • Si CPU > 80%, reduce límites
    • Si CPU < 50%, puedes incrementar

Fórmula Rápida

Límite Global = (Usuarios Concurrentes × Límite Individual) × Factor de Seguridad

Factor de Seguridad:
- 1.5 = Servidor robusto, tráfico predecible
- 1.3 = Servidor normal, tráfico variable
- 1.2 = Servidor limitado, tráfico impredecible

Usar Redis en Producción

⚠️ Importante: memory:// no es apropiado para producción con múltiples workers.

Instalar Redis

Bash 
# Docker
docker run -d -p 6379:6379 redis:alpine

# macOS
brew install redis
brew services start redis

# Ubuntu/Debian
sudo apt install redis-server
sudo systemctl start redis

Configurar

.env 
RATE_LIMIT_STORAGE_URI=redis://localhost:6379

Redis con Autenticación

.env 
RATE_LIMIT_STORAGE_URI=redis://:password@localhost:6379

Redis Cluster

.env 
RATE_LIMIT_STORAGE_URI=redis://node1:6379,node2:6379,node3:6379

Monitorización

Logs a Revisar

Bash 
# Ver límites excedidos
grep "Rate limit exceeded" logs/app.log

# Ver por usuario
grep "Rate limit exceeded: user:" logs/app.log | sort | uniq -c

# Ver por IP
grep "Rate limit exceeded: [0-9]" logs/app.log | sort | uniq -c

Métricas Recomendadas

  1. Tasa de error 429
    • < 1% = OK
    • 1-5% = Revisar
    • > 5% = Límites muy bajos o ataque DoS
  2. Distribución de uso
    • Ver qué usuarios/IPs consumen más
    • Identificar posibles abusos
  3. Uso de límite global
    • Si se alcanza frecuentemente, considera escalar verticalmente

Troubleshooting

Problema: Muchos 429 en producción

Síntomas: Usuarios legítimos reciben 429

Causas posibles:

  1. Límites muy bajos
  2. Límite global alcanzado por tráfico legítimo alto
  3. Bot o crawler agresivo

Soluciones:

  1. Incrementar RATE_LIMIT_GLOBAL_BURST
  2. Identificar y bloquear bots (User-Agent)
  3. Escalar servidor

Problema: Límite global no se respeta

Síntomas: Más peticiones de las esperadas

Causas posibles:

  1. Usando memory:// con múltiples workers Gunicorn
  2. Rate limiter no inicializado correctamente

Soluciones:

  1. Cambiar a Redis: RATE_LIMIT_STORAGE_URI=redis://localhost:6379
  2. Verificar logs de inicio: "✅ Rate limiter inicializado"

Problema: Alto uso de memoria Redis

Síntomas: Redis consume mucha RAM

Causas posibles:

  1. Muchos usuarios únicos (cada uno tiene entrada)
  2. Ventanas de tiempo muy largas

Soluciones:

  1. Reducir ventanas (ej: 30 min en vez de 1 hora)
  2. Configurar eviction policy en Redis: maxmemory-policy allkeys-lru

Seguridad

Prevenir Bypass

❌ NO hagas esto:
Python 
# Cliente puede cambiar IP y bypass
if client_ip in whitelist:
    skip_rate_limit()
✅ Haz esto:
Python 
# Usa tokens de servicio con límites más altos
if has_service_token():
    apply_higher_limits()

Whitelist de IPs

Si necesitas whitelist (ej: servicios internos):

Python 
# En rate_limiter.py
WHITELISTED_IPS = os.getenv('RATE_LIMIT_WHITELIST_IPS', '').split(',')

def get_identifier():
    ip = get_remote_address()
    if ip in WHITELISTED_IPS:
        return f"whitelisted:{ip}"  # Sin límite o límite superior
    # ... resto del código

Testing

Test de Límite Individual

Bash 
# Debe fallar después de 50 peticiones
for i in {1..60}; do
  curl -H "Authorization: Bearer $TOKEN" http://localhost:5000/contratos
done

Test de Límite Global

Bash 
# Simular 30 usuarios simultáneos
seq 1 30 | xargs -P30 -I{} bash -c '
  for i in {1..40}; do
    curl -s http://localhost:5000/tarifas > /dev/null
  done
'
# Debería empezar a dar 429 después de 1000 peticiones totales

Última actualización: 10 de Febrero, 2026