Cuando un flujo de n8n falla, el lienzo suele mostrar solo una línea roja. La información realmente útil está en el registro de ejecución: el código de estado HTTP, el error code que devuelve el upstream y la dirección a la que se envió la petición. Con esos tres datos, la mayoría de los errores se localiza en pocos minutos.

Este artículo los separa por tipo: 401 y 403 pertenecen a credenciales y permisos; 404 casi siempre es la Base URL o el nombre del modelo; 429 es límite de tasa y cuota; los timeouts de nodo y los flujos fallidos dependen de la configuración y del entorno de ejecución; al final, los fallos de análisis JSON. El artículo termina con un orden de revisión fijo que el equipo puede convertir en su propio runbook.

Nota: n8n y OpenAI son marcas de sus respectivos titulares; este artículo no guarda relación de afiliación con esos fabricantes. Los nombres de modelo y los precios se rigen por la página de precios de modelos, y los campos de los nodos dependen de la versión que estés usando.

1. Mira primero el registro de ejecución, no adivines

Abre Executions en el menú izquierdo, filtra por Failed y entra en la ejecución fallida; revisa la entrada, la salida y el detalle del error nodo por nodo. Anota cuatro cosas: nombre del nodo, código de estado HTTP, error code del upstream y request ID (si existe). Esos cuatro datos determinan si el problema está en la configuración de n8n, en la ruta de red o en el servicio upstream.

Los códigos de estado más habituales se pueden clasificar a grandes rasgos con esta tabla:

Código Significado habitual Qué revisar primero
401 Sin autenticar o clave no válida Credencial seleccionada, caducidad de la clave
403 Autenticado pero sin permiso Permisos del modelo, lista blanca de IP
404 Dirección o modelo inexistente Ruta de la Base URL, ortografía del nombre del modelo
429 Límite de tasa o cuota agotada Concurrencia, política de reintentos, cuota de la cuenta
400 Parámetros de petición no válidos Nombres de campo, longitud del contexto, formato de mensajes
5xx Fallo temporal del upstream Reintentar más tarde, consultar la página de estado del servicio

2. 401: la clave puede ser correcta y aun así fallar

Un 401 no siempre significa «clave mal escrita». También aparece cuando la credencial se creó pero no se seleccionó en el nodo del flujo; cuando al copiar se colaron espacios o saltos de línea; cuando la clave de prueba fue desactivada; cuando varias personas comparten la instancia y el nodo referencia otro conjunto de credenciales; o cuando se cambió N8N_ENCRYPTION_KEY en una instancia autoalojada y las credenciales antiguas ya no se descifran.

El orden de tratamiento es simple: vuelve a seleccionar la credencial, vuelve a pegar la clave, guarda y ejecuta ese nodo por separado. Si sigue fallando, ejecuta curl desde una máquina que represente el entorno de ejecución de n8n:

curl -i https://tu-direccion-de-pasarela/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tu-nombre-de-modelo","messages":[{"role":"user","content":"Responde solo OK"}]}'

Si curl funciona y n8n falla, el problema está en la credencial o en la configuración del nodo; si fallan ambos, está en la clave, en la pasarela o en la red. No escribas la clave en nodos Code, en el JSON del flujo ni en campos de notas: todos esos lugares se exportan y se comparten con facilidad.

3. 404: la Base URL y el nombre del modelo se reparten la culpa

En una credencial de tipo OpenAI, la Base URL suele escribirse hasta /v1, y el nodo añade /chat/completions por su cuenta. Si escribes una ruta completa de más, aparecen direcciones como /v1/chat/completions/chat/completions y la respuesta es 404. A la inversa, el nodo HTTP Request necesita la URL completa y no basta con el dominio.

La otra mitad de los 404 viene del nombre del modelo. Los servicios compatibles con OpenAI suelen usar model_not_found para indicar que el modelo no existe; puede devolver 404 o venir envuelto en un 400. Verifica tres cosas: mayúsculas del nombre, si lleva sufijo de fecha y si la pasarela usa un alias o el nombre original del upstream. Lo más fiable es pedir /v1/models y usar solo nombres que aparezcan en la lista devuelta.

Hay más detalles: una barra final de más en la Base URL puede producir una barra doble; si la pasarela está montada bajo una subruta de un proxy inverso, el prefijo no se puede omitir; y al cambiar entre pruebas y producción es frecuente olvidar actualizar la dirección.

4. 429: el límite de tasa no se resuelve solo con reintentos

Un 429 indica que la petición fue limitada. Los detonantes habituales son tres: se superó el número de peticiones o de tokens por minuto, se superó la concurrencia o la cuota o el saldo de la cuenta se agotó. Si la cabecera Retry-After trae un valor, hay que respetarlo antes que reenviar de inmediato.

En los ajustes del nodo de n8n se puede activar Retry On Fail, fijar el número máximo de intentos en 2 o 3 y definir una espera creciente. Pero los reintentos solo absorben fluctuaciones cortas, no resuelven un exceso sostenido. Para tareas en lote, reduce la concurrencia y procesa por lotes con Split In Batches o Loop Over Items, dejando un intervalo entre lotes; escalona las tareas programadas; y no ejecutes sobre todos los datos durante la depuración.

5. Timeouts de nodo y flujos fallidos

En los timeouts hay que distinguir niveles: el timeout propio del nodo HTTP Request, el timeout a nivel de flujo, el del proxy inverso o balanceador y el tiempo de generación del modelo upstream. El primero que venza hace fallar la ejecución, y el mensaje de error suele tener una redacción distinta en cada caso.

La generación de textos largos supera con facilidad el límite predeterminado. Puedes ampliar moderadamente el timeout del nodo y, al mismo tiempo, comprimir la entrada, limitar la salida máxima y dividir la tarea. No dejes que el flujo espere indefinidamente ni configures un timeout tan alto que, ante un fallo, ocupe una ranura de ejecución durante mucho tiempo. En instancias autoalojadas, comprueba también si el proceso se reinició y si los workers del modo cola están en línea.

La política de fallo a nivel de nodo también debe configurarse: en tareas por lotes, usa On Error para continuar y conservar los elementos con error; en nodos críticos de escritura, elige detener el flujo. Añade además un Error Workflow que envíe el ID de ejecución, el nombre del nodo y un resumen de la entrada a un chat de equipo o por correo. Que un flujo falle no es grave; lo grave es que no quede registro.

6. Fallo de análisis JSON: la salida del modelo no es JSON

El error típico es JSON parameter needs to be valid JSON, o una excepción de JSON.parse en un nodo Code. La causa suele ser que el modelo añadió texto explicativo o un bloque de código Markdown alrededor del JSON, o que los tipos de campo no coinciden con lo acordado.

Resuélvelo primero en el upstream: indica en el prompt «devuelve solo JSON, sin bloques de código», especifica campos y tipos, y usa la salida estructurada cuando la pasarela o el modelo la admitan. En el downstream, analiza siempre de forma defensiva, por ejemplo en un nodo Code:

const raw = $json.text ?? $json.content ?? "";
const cleaned = String(raw)
  .replace(/^```(?:json)?\s*/i, "")
  .replace(/```\s*$/, "")
  .trim();

try {
  return [{ json: JSON.parse(cleaned) }];
} catch (e) {
  return [{ json: { parse_error: true, raw: cleaned } }];
}

Si el análisis falla, no descartes el dato en silencio: escribe el texto original en una tabla de excepciones y revisa algunas muestras a mano; así suelen aparecer problemas del prompt o de la capacidad del modelo.

7. Un orden de diagnóstico reutilizable

  1. Confirma el alcance: ¿falla un solo registro, todo el lote o todo el flujo?
  2. Reproduce con curl desde la misma red que n8n para descartar la interferencia de la configuración del nodo.
  3. Compara la URL, las cabeceras y el cuerpo que envía realmente n8n, con especial atención al ensamblado de la Base URL.
  4. Pide /v1/models para verificar el nombre del modelo, las mayúsculas y el sufijo.
  5. Registra el código de estado y el error code: 401, 403 y 404 no se reintentan; 429, 5xx y los timeouts sí pueden merecer un reintento.
  6. Revisa timeout, concurrencia y tamaño de lote antes de decidir si ajustas los parámetros de reintento.
  7. Escribe la conclusión en el runbook del equipo, con ejemplos de error y la acción de corrección.

Preguntas frecuentes

n8n devuelve 401, pero curl funciona: ¿dónde está el problema?

Revisa primero si el nodo referencia la credencial equivocada, si la clave tiene espacios o saltos de línea de más y si la instancia cambió alguna vez la clave de cifrado. También puedes añadir manualmente la cabecera Authorization en el nodo HTTP Request para comparar y confirmar si el problema está en el análisis de la credencial o en la construcción de la petición.

¿Un 404 significa siempre que la Base URL está mal?

No necesariamente. Una ruta de más, la falta de /v1 o la pérdida del prefijo del proxy inverso también producen 404; además, un nombre de modelo inexistente puede devolver 404. Confirma primero con /v1/models que el modelo existe y después revisa el nivel de la dirección.

¿Cuántos reintentos conviene hacer ante un 429?

Normalmente 2 o 3, con espera creciente y respetando Retry-After. Un 429 sostenido indica que la concurrencia o la cuota ya se superaron; seguir reintentando solo aumenta la congestión, así que reduce el tamaño del lote o escalona la ejecución.

El flujo muestra éxito, pero el resultado está vacío: ¿cómo lo investigo?

Abre el registro de ejecución y revisa la salida nodo por nodo; confirma si la respuesta del modelo fue sobrescrita por el mapeo de campos posterior, si la salida se truncó o si se activó el filtro de contenido; después verifica que los nombres de campo de la expresión coinciden con la estructura real del paso anterior.

¿Qué problemas de red hay que revisar en n8n autoalojado?

Confirma que el contenedor o el host puede resolver y acceder al dominio de la pasarela; revisa las variables de proxy, las reglas de salida del firewall y la lista blanca de IP. Los disparadores programados y las ejecuciones manuales pueden pasar por instancias distintas, así que valida ambos entornos.

Siguiente paso

El principio general para diagnosticar errores es: primero reúne pruebas, después cambia la configuración; primero corrige la dirección y la credencial, y luego habla de reintentos y timeouts. Si necesitas un punto de entrada unificado compatible con OpenAI, claves virtuales independientes y registros de consumo, puedes registrarte en ZSQH AI Gateway; los modelos y los precios se rigen por la página de precios de modelos.

Lecturas relacionadas: