Módulo 3: Loops e Iteraciones

Patrones de Loop con SplitInBatches

Descripción de la cápsula

SplitInBatches es la herramienta. Los patrones son cómo la usas en escenarios reales. En esta cápsula vas a aprender los 4 patrones más comunes de loops en producción: procesar todos los items, loop con condición de salida, retry de items fallidos, y procesamiento secuencial estricto. Cada uno con su estructura, casos típicos, y consideraciones.

Estos patrones cubren ~90% de los casos donde necesitas iteración explícita. Dominarlos te da las herramientas para procesar listas grandes, integrar con APIs limitadas, y construir workflows robustos que manejan volumen sin colapsar.

Lo que vas a aprender

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

✅ Aplicar los 4 patrones según el caso
✅ Combinarlos cuando un workflow lo requiere
✅ Reconocer cuándo cada patrón es la respuesta
✅ Estructurar loops mantenibles

Patrón 1: Process all (procesa todos los items)

El más común. Recibes N items, los procesas todos en batches, terminas cuando el último batch está listo.

Estructura

[Input: N items]
   │
[SplitInBatches batch=10]
   │ (loop)
   ▼
[procesa cada item del batch]
   │
   └─→ loop back
   │
[Done]
   │
[acción final / resumen]

Casos típicos

Procesar todos los leads del Sheet diario
Enviar emails a una lista de suscriptores
Sincronizar todos los registros de un CRM
Enriquecer todos los contactos con API externa

Ejemplo concreto

Procesar 500 leads del Sheet, enviar email a cada uno:

[Sheets: 500 leads]
   │
[SplitInBatches batch=20]
   │
   ▼
[Filter: solo válidos]
   │
[Send Email]
   │
[Wait 5 seconds] ← rate limit del SMTP
   │
   └──→ loop back
   │
[Done]
   │
[Slack: "Procesados 500 leads"]

Patrón 2: Loop until condition (loop hasta cumplir condición)

A veces no sabes cuántas iteraciones necesitas — paras cuando se cumple cierta condición. Ejemplos: paginación de API (sigue hasta que no haya next_page), polling hasta que un job esté complete, scrape hasta encontrar X resultados.

Estructura

[Inicio: cursor o estado inicial]
   │
[SplitInBatches batch=1]
   │ (loop)
   ▼
[Hacer una llamada / acción con cursor actual]
   │
[IF: condición de salida cumplida?]
   ├─ TRUE → [Done] → fin
   └─ FALSE → [Actualizar cursor] → loop back a SplitInBatches

Casos típicos

Paginación: "GET /api/users?page=1", devuelve next_page=2, sigues hasta next_page=null
Polling de jobs: "GET /api/job/123", devuelve status: running, esperas y vuelves hasta status: complete
Scrape progresivo: scroll infinito en un sitio, paras al ver "no más resultados"

Ejemplo: paginación

Llamar API que devuelve usuarios en páginas de 100:

[Manual] (inicial: page=1)
   │
[SplitInBatches batch=1]
   │ (loop)
   ▼
[HTTP Request: /api/users?page={{ page }}]
   │
[Set: agregar items a array global, actualizar page = response.next_page]
   │
[IF: response.next_page === null]
   ├─ TRUE → [Done] → fin
   └─ FALSE → loop back

Nota: este patrón con SplitInBatches batch=1 es uno de los más confusos. Alternativa: usar un nodo Code con un loop nativo de JavaScript si la lógica es muy específica.

Patrón 3: Retry failed items

Procesas N items. Algunos fallan (API timeout, datos malformados). Quieres reintentar solo los fallidos sin volver a procesar los exitosos.

Estructura

[Lista de items]
   │
[SplitInBatches batch=10]
   │
   ▼
[HTTP con Continue on Fail]
   │
[IF: $json.error existe?]
   ├─ TRUE → [Sheet: append a "failed_retries"]
   └─ FALSE → [Sheet: append a "successful"]
   │
   └─→ loop back

Después del primer pase

Otro workflow (o el mismo en otra ejecución):

[Sheets: leer "failed_retries"]
   │
[SplitInBatches batch=5]
   │ (con configuración de retry más conservadora: menos paralelismo, más wait)
   │
   ▼
[HTTP retry]
   │
[IF: si falla otra vez → "permanently_failed"]
   │
   └─→ loop back

Casos típicos

Sincronización con CRM donde algunos contactos fallan
Enrichment con API externa que ocasionalmente tiene 503
Envío de emails con algunos addresses inválidos

Patrón 4: Strict sequential (procesamiento estricto en orden)

Algunos casos requieren orden estricto: item 2 espera a que item 1 termine completamente antes de empezar.

Estructura

Simple: batch_size = 1.

[Lista en orden]
   │
[SplitInBatches batch=1]  ← clave
   │
   ▼
[procesamiento que debe ser secuencial]
   │
   └─→ loop back

Casos típicos

Migración de datos donde cada paso depende del anterior
Operaciones que modifican estado compartido (mismo registro)
APIs que tienen restricción "1 operación por usuario activa"

Ejemplo

Procesar lista de tickets de soporte. Cada uno modifica el mismo Sheet de tracking. Quieres que se procesen en orden de llegada:

[Tickets ordenados por fecha]
   │
[SplitInBatches batch=1]
   │
   ▼
[Procesar ticket]
   │
[Update Sheet tracking]
   │
   └─→ loop back to SplitInBatches

Cada ticket espera a que el anterior termine de actualizar el Sheet.

Combinar patrones

Workflows reales suelen combinar 2+ patrones:

Ejemplo: process all + retry pattern

[Items]
   │
[SplitInBatches]
   │
[HTTP con Continue on Fail]
   │
[IF: error?]
   ├─ TRUE → guardar en "to_retry"
   └─ FALSE → guardar en "ok"
   │
   └─→ loop back

[Done]
   │
[Lee "to_retry"]
   │
[Otro SplitInBatches con configuración más conservadora]
   │
[Retry HTTP]
   ...

Process all en primera pasada + retry pattern en segunda.

Decisión: qué patrón aplicar

Necesidad	Patrón
Procesar todos, rate limit	Process all + Wait
Procesar todos, sin rate limit (memoria)	Process all batch grande
Paginación de API	Loop until condition
Polling hasta complete	Loop until condition
Orden estricto entre items	Strict sequential (batch=1)
Retry de fallos	Retry failed items
Migración con dependencia	Strict sequential

Trampas comunes

Trampa 1: Loop infinito

Qué pasa: Patrón "loop until condition" mal configurado — la condición nunca se cumple. El workflow corre infinitamente (o hasta timeout).

Cómo evitar:

Siempre incluir contador de seguridad ("máximo 100 iteraciones") con IF de salida
Testear con escenarios donde condición sí se cumple
En APIs, verificar que el cursor realmente avanza

Trampa 2: SplitInBatches sin loop back

Qué pasa: Conectas SplitInBatches a procesamiento pero olvidas el loop back. Solo procesa el primer batch.

Cómo evitar: Verificar visualmente que el loop se cierra. El último nodo del procesamiento debe tener una conexión de vuelta a SplitInBatches.

Trampa 3: Patrón retry sin distinguir errores transitorios vs permanentes

Qué pasa: Reintentas un error 404 (no existe) 5 veces. Nunca va a funcionar — es permanente.

Cómo evitar: Antes de retry, verificar tipo de error:

5xx, timeout, rate limit (429) → transitorio, retry vale
4xx (excepto 429) → permanente, no retry

Trampa 4: Batch size 1 cuando podría ser 10

Qué pasa: Usas batch=1 "por seguridad" cuando no hay razón. Procesamiento 10× más lento que necesario.

Cómo evitar: Batch=1 solo si necesitas orden estricto o dependencias entre items. Default razonable: 10-50.

Trampa 5: No agregar Wait en loops con APIs externas

Qué pasa: Loop ejecuta los batches lo más rápido posible. API externa te da rate limit en el batch 3.

Cómo evitar: Wait dentro del loop entre batches, según rate limit del servicio. Cápsula 05 cubre esto en detalle.

Ejercicio: identificar patrón correcto

Objetivo: practicar elegir el patrón según caso.

Casos

Para cada caso, identifica el patrón:

Procesar 500 órdenes del Sheet, enviar email a cliente de cada una. API SMTP tiene rate limit 10/min.
Llamar API de Shopify que devuelve productos en páginas de 50. Quieres todos los productos. La API tiene has_next_page flag.
Migrar 200 contactos a CRM. Cada migración crea registros relacionados que deben existir antes del siguiente contacto.
Procesar 1000 leads. Llamas API de enrichment. ~5% falla por timeout. Quieres reintentar los fallos.
Job a un API externo que toma minutos. Quieres "esperar" hasta que esté complete (status=done).

Respuestas

Process all + Wait — batch pequeño + wait según rate limit
Loop until condition — paginación clásica, termina cuando has_next_page = false
Strict sequential — batch=1 para mantener orden y dependencias
Process all + Retry failed items — primera pasada con Continue on Fail, segunda solo retry de los fallidos
Loop until condition — poll hasta status === "done"

Resumen y siguiente paso

4 patrones principales: process all, loop until condition, retry failed, strict sequential
Process all es el más común — 80% de casos
Loop until condition para paginación y polling
Retry failed para resiliencia con APIs flakies
Strict sequential (batch=1) cuando orden es crítico
Combinar patrones cuando workflow lo requiere
5 trampas: loop infinito, sin loop back, retry sin distinguir errores, batch=1 sin razón, sin Wait

Antes de avanzar deberías poder:

Aplicar los 4 patrones según caso
Reconocer cuándo combinar patrones
Implementar paginación con loop until condition

Lo que sigue (cápsula 05):

Hemos mencionado Wait varias veces. La cápsula 05 lo cubre en profundidad: configuración, casos de uso (rate limiting, scheduling de retries, esperar eventos), y los matices que importan en producción.

Recursos adicionales

Looping Patterns (n8n Docs) - Referencia oficial.
API Pagination Patterns - Conceptos generales.

Creado: Mayo 11, 2026 Versión: 1.0

← AnteriorSplitInBatches: El Nodo Principal de Loops Siguiente →Rate Limiting con Wait Node