Módulo 3: Loops e Iteraciones

Rate Limiting con Wait Node

Siguiente →

Descripción de la cápsula

Cuando llamas APIs externas en bucle, rate limits son la realidad: casi todas las APIs profesionales te limitan a X requests por minuto, hora, o día. Excederlos significa rejection con error 429, ban temporal, o incluso permanente. Wait node es la herramienta para regular la velocidad de tus loops.

En esta cápsula vas a aprender a calcular cuánto Wait según el rate limit del servicio, los 3 patrones principales (Wait fijo, Wait variable según respuesta, Wait exponencial para retry), cómo detectar rate limits dinámicamente desde la respuesta del servidor, y los matices de plan rate vs burst rate que las APIs usan.

Lo que vas a aprender

Al terminar esta cápsula serás capaz de:

  • ✅ Calcular Wait time según rate limit del servicio
  • ✅ Configurar Wait node en diferentes modos
  • ✅ Aplicar 3 patrones: fijo, dinámico, exponencial
  • ✅ Detectar rate limits desde headers de respuesta
  • ✅ Manejar burst vs plan rate
  • ✅ Implementar backoff exponencial para retries

Conceptos clave: tipos de rate limits

Plan rate

"X requests por unidad de tiempo, total".

  • Stripe: 100 read / 100 write por segundo
  • OpenAI: tokens por minuto + RPM (requests por minuto)
  • Slack: ~1 message per second por canal

Burst rate

A veces permite picos cortos. Ejemplo: "100 RPM con burst de 10/segundo en cortos periods".

Diaria/mensual

Algunas APIs tienen quotas diarias o mensuales (no rate por segundo, sino quota total).

  • OpenAI free tier: 200 requests/day
  • Gmail API: 1B quota/day

Por endpoint vs global

Algunas APIs separan rate por endpoint:

  • /api/users: 1000/min
  • /api/exports: 10/min

Otras tienen pool compartido.

Calcular Wait time

Si la API permite X requests por segundo:

wait_seconds = 1 / X

Si API permite 10 RPS → Wait 100ms entre requests.

Si batch = N items por batch, considera que cada batch consume N requests:

wait_per_batch = N / X_per_second

Batch de 10, API permite 10/segundo → Wait 1 segundo entre batches.

Ejemplo: OpenAI Tier 1

  • 500 RPM = ~8 RPS
  • Batch de 5 → 5/8 = ~0.6 segundos entre batches
  • Conservador: Wait 1 segundo (margen)

Ejemplo: SendGrid Free

  • 100 emails/day (1 por minuto promedio)
  • Batch de 1 → Wait 60 segundos entre batches
  • Si necesitas mandar 500/día → no alcanza el free tier, upgrade

Wait node: configuración

Modo 1: Wait amount (espera fija)

  • Wait Amount: valor numérico
  • Wait Unit: seconds, minutes, hours

Simple y suficiente para la mayoría de rate limits.

Modo 2: Wait until (espera hasta cierta fecha/hora)

  • Wait Until: timestamp ISO 8601
  • Útil cuando necesitas esperar hasta cierto reset (ej. "API resetea quota a medianoche UTC")

Modo 3: Wait for webhook

  • Espera hasta que llegue una request HTTP específica
  • Para flows asíncronos (cubierto en M07)

Patrón 1: Wait fijo

[SplitInBatches batch=10]
   │
[HTTP API call]
   │
[Wait: 1 second]
   │
   └─→ loop back

Cuándo:

  • API tiene rate limit conocido y constante
  • Quieres simplicidad

Cuándo no alcanza:

  • Rate limit cambia dinámicamente
  • API te devuelve Retry-After header con tiempo específico

Patrón 2: Wait dinámico desde headers

Algunas APIs devuelven headers como:

  • X-RateLimit-Remaining: 5 (cuántos quedan)
  • X-RateLimit-Reset: 1654000000 (timestamp del reset)
  • Retry-After: 30 (en error 429, cuánto esperar)

Implementación

[HTTP API call con Continue on Fail]
   │
[IF: response status === 429]
   ├─ TRUE → [Set: wait_seconds = response.headers['retry-after']]
   │         → [Wait: dinámico según wait_seconds]
   │         → retry
   └─ FALSE → continuar normal

Wait node con expression

n8n permite Wait Amount como expression:

{{ Number($json.headers['retry-after']) || 5 }}

Espera lo que el servidor dice, o 5 segundos si no está el header.

Patrón 3: Exponential backoff

Para retry de errores transitorios: espera creciente entre reintentos.

intento 1: wait 1s
intento 2: wait 2s
intento 3: wait 4s
intento 4: wait 8s
intento 5: wait 16s

Por qué exponencial

  • Si el servicio está saturado, darle tiempo de recuperarse
  • Más respetuoso con el provider
  • Stripe, AWS, Google APIs lo recomiendan

Implementación

Set node calcula el wait basado en intento actual:

[Set:]
  wait_seconds: {{ Math.pow(2, $json.retry_count) }}
  // 1, 2, 4, 8, 16...

Y aumentas retry_count en cada loop iteration.

Cap (límite máximo)

Sin cap, después de 10 retries esperarías 1024 segundos (~17 min). Cap al máximo razonable:

wait_seconds: {{ Math.min(Math.pow(2, $json.retry_count), 60) }}
// Capped at 60s

Detectar rate limits proactivamente

En lugar de esperar a recibir 429, monitorear X-RateLimit-Remaining:

[HTTP API call]
   │
[Set: extraer header remaining]
   │
[IF: remaining < 10]
   ├─ TRUE → [Wait: tiempo hasta reset (calculado del header)]
   └─ FALSE → continuar normal

Ventaja: evitas el 429 entirely, ralentizando proactivamente.

Ejemplo: workflow con rate limit completo

Procesar 500 leads con OpenAI (categorizar cada uno).

Plan: OpenAI Tier 1 = 500 RPM = ~8 RPS.

Diseño:

[Sheet: 500 leads]
   │
[SplitInBatches batch=5]
   │
   ▼
[5 paralelos a OpenAI] (5 RPS, dentro del limit)
   │
[Set: capturar response]
   │
[IF: status === 429]
   ├─ TRUE → [Wait: response.headers.retry-after]
   │         → retry desde el OpenAI call
   └─ FALSE → continuar
   │
[Wait: 1 segundo fijo entre batches (margen)]
   │
   └─→ loop back

[Done]
   │
[Slack: "500 leads categorizados"]

Cálculo:

  • 500 / 5 = 100 batches
  • Cada batch: ~1-2s para 5 paralelas + 1s wait
  • Total ~3 min, sin rate limits

Calcular tiempo total

Para presentar a stakeholders o decidir si vale la pena:

total_time = (N_items / batch_size) × (batch_processing + wait_between_batches)

Ejemplo:

  • 500 items
  • Batch 10
  • Procesamiento batch: 2s
  • Wait entre batches: 3s

Total: (500/10) × (2+3) = 50 × 5 = 250 segundos ≈ 4 min

Si es para un Schedule diario, OK. Si es real-time response, demasiado.

Trampas comunes

Trampa 1: Wait too short

Qué pasa: Wait 100ms creyendo que es suficiente. API devuelve 429.

Cómo evitar: Empezar conservador. Si rate limit es 10 RPS, Wait 200ms en lugar de 100ms — margen para latencia.

Trampa 2: Wait too long

Qué pasa: Wait 10 segundos "por seguridad". 1000 items × 10s = 3 horas.

Cómo evitar: Calcular con margen razonable (20% más que el mínimo).

Trampa 3: No respetar Retry-After

Qué pasa: Recibes 429 con Retry-After: 60. Tu workflow hace retry inmediato. La API te bloquea por abuso.

Cómo evitar: Siempre respetar Retry-After si está. Lo cubrí arriba.

Trampa 4: Wait fuera del loop

Qué pasa: Wait después de SplitInBatches Done, no dentro del loop. Wait solo se ejecuta una vez al final.

Cómo evitar: Wait dentro del loop, entre llamadas API.

Trampa 5: No diferenciar rate limit transient vs daily quota

Qué pasa: Recibes 429. Wait 1 minuto. Vuelve a fallar. Wait 1 min. Falla. Es daily quota exceeded, no rate per second — esperar no ayuda hasta el día siguiente.

Cómo evitar: Leer el error completo. Si menciona "daily" o "monthly quota", detener el workflow y notificar — no retry inútil.

Ejercicio: calcular Wait

Objetivo: practicar el cálculo.

Casos

Para cada API, calcula el Wait correcto:

  1. API permite 60 RPM. Batch=10. ¿Wait entre batches?

  2. API permite 1000 RPS pero con burst de 50/sec. Batch=20. ¿Wait?

  3. API tiene 500 calls/day. Quieres procesar 100 items hoy. ¿Wait?

  4. Tu workflow falla con 429 + Retry-After: 30. ¿Qué Wait usar?

Respuestas
  1. 60 RPM = 1 RPS. Batch=10 → 10 calls. Wait = 10 segundos entre batches.
  2. Within burst (50/sec), batch=20 está OK. Wait corto (1s) entre batches. Si haces muchos batches seguidos, considera Wait más largo cada 5 batches para no agotar burst.
  3. 500/day = ~5 per minute on average. Para 100 items, podrías hacerlos en ~20 min con Wait 12s entre cada uno. Pero si solo necesitas 100, podrías hacer en batch denso y dejar quota para resto del día.
  4. Wait 30 segundos según el header. Después, retry desde el punto fallido.

Resumen y siguiente paso

  • Wait node regula velocidad de loops para respetar rate limits de APIs
  • 3 patrones: fijo (simple), dinámico desde headers (preciso), exponencial (retry)
  • Calcular Wait: considerar rate del servicio + tamaño del batch
  • Respetar Retry-After cuando aparezca
  • Detectar rate limits proactivamente monitoreando X-RateLimit-Remaining
  • Daily quota ≠ rate limit — daily quotas no se resuelven con Wait
  • 5 trampas: wait too short/long, no respect Retry-After, wait fuera del loop, no distinguir transient vs daily

Antes de avanzar deberías poder:

  • Calcular Wait según rate limit
  • Implementar Wait dinámico desde headers
  • Implementar exponential backoff con cap

Lo que sigue (cápsula 06):

Después de procesar todos los items en lotes, a veces necesitas juntar todos los resultados en una sola pieza para reporte/notificación/storage. Aggregate node es la herramienta: colapsar N items en 1 con array adentro.

Recursos adicionales

  1. Wait Node Documentation - Referencia.
  2. Exponential Backoff (Google Cloud) - Concepto general.
  3. Rate Limiting Strategies (Stripe) - Estrategias profesionales.

Creado: Mayo 11, 2026 Versión: 1.0

← AnteriorPatrones de Loop con SplitInBatchesSiguiente →Aggregate: Juntar Resultados