Módulo 6: Manejo de Errores

Tipos de Errores y Estrategias

Siguiente →

Descripción de la cápsula

No todos los errores son iguales. Un timeout de red es distinto a una credencial inválida, distinto a un dato malformado. Tratar todos igual con la misma estrategia (ej. retry 3 veces) significa retry inútil para errores que no se resuelven solos y rendirse demasiado pronto para errores transitorios.

En esta cápsula vas a aprender a clasificar errores en categorías, qué estrategia aplicar a cada una, y cómo detectar el tipo desde el response del API.

Lo que vas a aprender

  • ✅ Clasificar errores en 5 categorías
  • ✅ Aplicar estrategia correcta según tipo
  • ✅ Detectar tipo desde status codes y mensajes
  • ✅ Diseñar response apropiado por categoría

Las 5 categorías

Categoría 1: Transient (transitorio)

Errores que se resuelven solos con tiempo. Causas: red flakies, sobrecarga temporal, deploy en curso del API.

Indicadores:

  • HTTP 502, 503, 504
  • Timeouts de conexión
  • "Service temporarily unavailable"

Estrategia: Retry con exponential backoff. Suele funcionar.

Categoría 2: Rate Limit

API rechaza porque excediste su quota.

Indicadores:

  • HTTP 429
  • Headers X-RateLimit-Remaining: 0
  • Mensaje "rate limit exceeded"

Estrategia: Wait + retry, respetando Retry-After header si está. NO acumular retries rápidos — empeora la situación.

Categoría 3: Auth

Credenciales inválidas o expiradas.

Indicadores:

  • HTTP 401, 403
  • "Invalid credentials", "Token expired"

Estrategia: NO retry. Retry no ayuda — la credencial no se va a arreglar sola. Alertar al equipo para rotar/renovar.

Categoría 4: Client Error (datos/lógica)

Tu request está mal armado, o referencia algo que no existe.

Indicadores:

  • HTTP 400, 404, 422
  • "Validation error", "Not found", "Bad request"

Estrategia: NO retry. Es bug del workflow o de los datos. Loggear y continuar (continue on fail) o detener si es crítico.

Categoría 5: Server Error (no transitorio)

Bug del API que no se resuelve con retry — algo está fundamentalmente roto del lado del servicio.

Indicadores:

  • HTTP 500 con mensaje específico de bug
  • Comportamiento inconsistente entre requests
  • Issues conocidos del provider

Estrategia: NO retry indefinido. 1-2 retries para descartar transitorio, después alertar.

Matriz de decisión

CategoríaRetry?Wait?Alert?Notes
Transient (502/503/504)✅ SíSí, exponentialNo (suele resolverse)Hasta 3-5 retries
Rate Limit (429)✅ SíSí, respetar Retry-AfterSi persisteNO retry rápido
Auth (401/403)❌ No—✅ InmediatoNecesita acción humana
Client (400/404)❌ No—Si críticoBug, no se arregla solo
Server bug (500)⚠️ 1-2YesSí si persisteDespués escalate

Detectar tipo desde response

En HTTP Request node

Después del HTTP, el $json contiene la respuesta. Para clasificar:

{{
  (() => {
    const status = $json.statusCode || $json.error?.status;

    if (status >= 500 && status !== 500) return 'transient';
    if (status === 500) return 'server_error';
    if (status === 429) return 'rate_limit';
    if (status === 401 || status === 403) return 'auth';
    if (status >= 400) return 'client_error';
    return 'success';
  })()
}}

Después, branch según categoría

[Set: error_category]
   │
[Switch sobre error_category]
├─→ "transient"     → Retry con backoff
├─→ "rate_limit"    → Wait Retry-After + retry
├─→ "auth"          → Slack alert al admin
├─→ "client_error"  → Log y continue
└─→ "server_error"  → 1 retry, después alert

Errores no-HTTP

A veces no es un HTTP request — es un error de Sheets, Code node, etc. Categorías similares aplican:

ErrorCategoría
"Cannot read property X of undefined"Client error (bug en expression)
"Spreadsheet not found"Client error (config)
"Quota exceeded"Rate limit
"Authentication failed"Auth
"ECONNREFUSED"Transient

Errores con tipo ambiguo

Algunos errores no encajan claramente. Casos:

"Bad Request" 400 — datos o config?

Si el campo X siempre da 400 pero a veces no:

  • Si los datos cambian → client error (datos)
  • Si la config cambió → bug
  • Si el API cambió validación → puede ser transitorio del provider

Estrategia: loggear con todos los detalles. Investigar manualmente.

"Internal Server Error" 500 con mensaje específico

Si el mensaje dice "Database connection failed" — probablemente transitorio. Si dice "Validation X failed" — client error disfrazado.

Estrategia: leer mensaje, no solo status code.

Trampas comunes

Trampa 1: Retry para todo

Qué pasa: Configuras retry on fail = ON en todos los nodos. Auth fallido → 3 retries → 3× la latencia, mismo error.

Cómo evitar: Retry solo para categorías transient y rate_limit.

Trampa 2: No alertar para auth errors

Qué pasa: Credencial expirada. Workflow falla silenciosamente día tras día. Nadie nota.

Cómo evitar: Alertar inmediato para auth errors. Sin acción humana, no se arreglan.

Trampa 3: Tratar 429 como retry simple

Qué pasa: API te dice "rate limit, espera 60 segundos". Tu workflow hace retry inmediato. Te bloquean por abuso.

Cómo evitar: Respetar Retry-After o esperar antes de retry.

Trampa 4: Retry indefinido

Qué pasa: Retry forever. Workflow nunca termina. Recursos consumidos para siempre.

Cómo evitar: Siempre tener max_retries (3-5 es razonable). Después de eso, alert + log + fail.

Resumen

  • 5 categorías: Transient, Rate Limit, Auth, Client, Server
  • Cada una requiere estrategia distinta
  • Detectar tipo desde status code + mensaje
  • Matriz de decisión te dice qué hacer
  • 4 trampas: retry para todo, no alertar auth, ignorar Retry-After, retry infinito

Lo que sigue: Retry strategies profundizadas — exponential backoff y configuración.

Creado: Mayo 11, 2026 Versión: 1.0

← AnteriorIntroducción al Módulo: Error Handling BásicoSiguiente →Retry Strategies Profundizadas