Los errores de Dify se dividen en dos capas: los que devuelve la API de una aplicación y los que produce Dify al llamar a un proveedor de modelos. Ambas capas pueden devolver 401, 404 o 429, pero lo que hay que investigar es completamente distinto. Si solo miras el código de estado, es fácil cambiar configuración en la capa equivocada una y otra vez.

Este artículo descompone los problemas en seis capas —autenticación, dirección, límite de tasa, flujo de trabajo, contexto y logs— y ofrece comandos mínimos de reproducción y un orden de diagnóstico fijo. Los códigos de error, los límites y los nombres de la interfaz se rigen por la documentación oficial de Dify y de los proveedores de modelos.

Nota: Dify es una marca de su titular y este artículo no implica afiliación con los fabricantes mencionados; los nombres de otros productos pertenecen a sus respectivos titulares. El artículo toma como referencia las versiones habituales de octubre de 2026.

1. Primero separa tres capas, no adivines desde el principio

Una solicitud pasa al menos por tres capas: el cliente, la API de la aplicación de Dify y el proveedor de modelos; entre medias puede haber además una pasarela. Un 401 puede originarse entre el cliente y Dify o entre Dify y el upstream; un 404 puede ser una ruta incorrecta o un nombre de modelo incorrecto; un 429 suele venir del upstream.

Mira primero el message, el code y el ID de solicitud del cuerpo de la respuesta, y después decide qué capa investigar. Una prueba útil: llama directamente a la API de la aplicación con curl; si el error se repite, el problema está en la configuración de Dify o en el upstream; si curl funciona y el código de negocio falla, el problema está en el cliente o en la red.

2. 401 y 403: no mezcles las dos claves

Dify maneja dos credenciales: la clave de API de aplicación sirve para llamar a una aplicación de Dify y la clave de proveedor sirve para que Dify llame al modelo upstream. La primera va en la cabecera Authorization: Bearer ...; la segunda se configura en los ajustes de proveedores de modelos. Mezclarlas es la causa más frecuente de 401.

Las causas habituales son:

  • Falta Bearer en la cabecera, o la clave lleva espacios, saltos de línea o comillas delante o detrás.
  • Se usa la clave de otra aplicación. Las claves de aplicación suelen crearse por aplicación y no funcionan entre aplicaciones.
  • La clave fue eliminada o rotada, o el espacio de trabajo no tiene acceso a esa aplicación.
  • La clave del proveedor caducó, no tiene saldo, fue revocada o se copió con caracteres faltantes.
  • El proxy inverso, la pasarela o el frontend filtran la cabecera Authorization.

El 403 suele relacionarse con permisos: rol insuficiente en el espacio de trabajo, proveedor sin ese modelo habilitado o cuenta upstream restringida. Confirma primero «quién llama a quién» y luego repite la prueba con otra clave.

3. 404 y modelo inexistente: revisa la dirección y el nombre por separado

Al llamar a la API de una aplicación de Dify, un 404 suele tener tres causas:

  1. Base URL incorrecta: la base de la API de aplicación de Dify Cloud es https://api.dify.ai/v1; en autoalojado se sustituye por tu dominio y ruta. Omitir /v1 o añadir la ruta completa del endpoint también produce 404.
  2. Endpoint que no corresponde al tipo de aplicación: las aplicaciones de chat usan chat-messages, las de flujo de trabajo usan workflows/run y las de generación de texto usan completion-messages. Con el endpoint equivocado, incluso una clave correcta devuelve 404 o 400.
  3. Ruta reescrita por el proxy inverso: las subrutas de Nginx, las barras finales y las reglas de reescritura de URL pueden enviar la solicitud a una ruta inexistente.

Si el error viene del proveedor de modelos, los mensajes habituales son model not found, model does not exist o invalid model. Comprueba que el ID coincida con el nombre que el proveedor tiene publicado, incluidas mayúsculas, sufijo de fecha y alias; confirma que el modelo está habilitado en Dify; y verifica que la versión del plugin lo admite. Si el modelo se retira o cambia de nombre, la configuración anterior deja de funcionar.

4. 429: límite de tasa, concurrencia y cuota

Normalmente el 429 no lo devuelve Dify, sino el servicio de modelos upstream o la pasarela indicando «demasiadas solicitudes». El disparador puede ser el número de solicitudes por minuto, los tokens por minuto, la concurrencia o la cuota de la cuenta. Las tareas por lotes, los nodos de iteración y el uso simultáneo de varias personas son los que más elevan la concurrencia instantánea.

Orden de tratamiento:

  • Revisa primero las cabeceras de respuesta y el mensaje para saber si el límite es de frecuencia, de tokens o de concurrencia.
  • Reduce la concurrencia del cliente y pon en cola las tareas por lotes; no satures de golpe.
  • Reintenta solo ante 429 y 5xx, con retroceso exponencial y jitter aleatorio, y fija un número máximo de intentos.
  • En los reintentos de flujos, cuida la idempotencia: una misma solicitud de negocio puede ejecutar nodos dos veces; conviene añadir una clave de deduplicación en la capa de negocio.
  • Si el límite se activa con frecuencia durante mucho tiempo, considera separar aplicaciones, claves o proyectos, o ajustar las franjas de llamada.

Reintentar a ciegas convierte el límite de tasa en una avalancha. Antes de reintentar, confirma si la solicitud ya produjo efectos secundarios.

5. Flujo de trabajo fallido: empieza por la entrada y la salida del nodo

Cuando un flujo falla completo, normalmente se puede localizar un nodo concreto. Tipos habituales:

Síntoma Causa frecuente Qué revisar primero
Variable de referencia vacía El nodo anterior no emitió esa variable o el nombre está mal escrito Estructura de salida del nodo y selector de variable
Tipo incompatible Se usa una cadena como arreglo u objeto Tipo devuelto por el nodo anterior y nodo de conversión
Error en nodo de código Sintaxis, dependencias, tiempo de espera o estructura de retorno incorrecta Logs de ejecución y convención del nodo de código
Fallo en nodo HTTP Código no 2xx, error de autenticación, tiempo de espera o certificado Código de estado, cabeceras y logs del servicio destino
Error al analizar la salida del LLM El modelo no devuelve el formato JSON esperado Restricciones del prompt y tolerancia del analizador
Recuperación de conocimiento vacía Índice incompleto, umbral demasiado alto o fallo de reescritura de consulta Estado de la base de conocimiento y parámetros de recuperación
Fallo en nodo de iteración La entrada no es un arreglo o el subflujo referencia mal Entrada de iteración y estructura de cada elemento

Los flujos de Dify admiten manejo de errores a nivel de nodo, por ejemplo reintentos, valores predeterminados o ramas de excepción. Dar una salida de respaldo a los nodos críticos es más controlable que dejar que falle toda la cadena. Pero no uses valores predeterminados para ocultar errores de configuración, porque el problema aparecerá más tarde en un nodo posterior.

6. Contexto y límite de tokens

Los errores de contexto suelen aparecer como 400 con mensajes context length exceeded, maximum context o token limit. La causa no es «que el modelo sea malo», sino que la suma de entrada y salida supera el límite permitido. Incluye el prompt del sistema, el historial, los fragmentos recuperados de la base de conocimiento, la entrada del usuario y la salida reservada.

Al diagnosticar, comprime punto por punto:

  • Limita el número de turnos del historial o resume antes de concatenar.
  • Reduce el número de fragmentos recuperados, activa el reranking y elimina fragmentos irrelevantes.
  • Ajusta el tamaño de segmentación de los documentos para que ningún bloque sea demasiado largo.
  • Fija por separado el máximo de tokens de salida y deja margen para la entrada.
  • Estima los tokens en el lado de la aplicación y trunca o deriva a un modelo de contexto largo antes de superar el límite.

La longitud de contexto configurada en Dify debe coincidir con lo que el proveedor admite realmente. Si pones más de lo que el upstream soporta, rechazará la solicitud; si pones menos, los documentos largos se truncarán antes de tiempo.

7. Logs y trazabilidad: une una solicitud completa

Para diagnosticar no basta con mirar la última frase. Conserva al menos cuatro tipos de información: logs de la aplicación y registros de ejecución de flujos de Dify, logs del proveedor de modelos, logs de solicitudes de la pasarela y, del lado del negocio, el usuario y el ID de solicitud. El historial de ejecución de Dify muestra la entrada, la salida y el tiempo de cada nodo, y es la primera entrada para localizar un fallo.

Si necesitas una traza más detallada, puedes integrar herramientas de tracing; las plataformas de observabilidad compatibles dependen de la documentación de la versión actual. Sea cual sea la herramienta, conviene registrar de forma uniforme el nombre del modelo, el ID de solicitud, la latencia, los tokens de entrada y salida, el código de error y el número de reintentos. Así los 429, los tiempos de espera y los cambios de modelo se detectan por tendencia, en lugar de esperar a que se queje un usuario.

8. Un orden de diagnóstico reutilizable

  1. Llama directamente a la API de la aplicación de Dify con curl -i y anota el código HTTP y el cuerpo de la respuesta.
  2. Confirma que la Base URL, el endpoint y el tipo de aplicación coinciden para descartar el 404.
  3. Confirma que no se mezclan la clave de aplicación y la clave de proveedor para descartar el 401.
  4. Prueba el proveedor de modelos por separado en la interfaz de Dify y confirma que el upstream responde.
  5. Abre el registro de ejecución del flujo, localiza el primer nodo que falla y revisa su entrada y salida.
  6. Revisa el contexto, el límite de salida y los parámetros de recuperación para descartar problemas de tokens.
  7. Consulta los logs del upstream y de la pasarela para confirmar 429, tiempos de espera o cuotas.
  8. Después de corregir, repite la misma batería de solicitudes y observa la tasa de errores durante un tiempo.

El comando mínimo de reproducción es el siguiente; -i permite ver a la vez el código de estado y las cabeceras:

export DIFY_API_KEY="app-tu-clave-de-aplicación"

curl -i -sS "https://api.dify.ai/v1/chat-messages" \
  -H "Authorization: Bearer $DIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {},
    "query": "Responde solo OK",
    "response_mode": "blocking",
    "user": "diag-001"
  }'

En autoalojado, sustituye la dirección por la de tu instancia; para una aplicación de flujo de trabajo, usa /v1/workflows/run y los parámetros correspondientes. Haz funcionar primero la solicitud mínima y añade después historial, base de conocimiento y herramientas; así localizarás rápido la capa del problema.

Preguntas frecuentes

La prueba del modelo funciona en Dify, pero la API de la aplicación devuelve 401. ¿Por qué?

No usan la misma clave. La prueba del modelo usa la clave del proveedor y la API de aplicación usa la clave propia de la aplicación. Revisa que la cabecera sea Bearer más la clave de aplicación y confirma que la clave pertenece a esa aplicación y a ese espacio de trabajo.

La dirección parece correcta, ¿por qué sigue dando 404?

La causa habitual es un endpoint que no corresponde al tipo de aplicación, o una Base URL con una ruta de más o de menos. Dify Cloud usa https://api.dify.ai/v1; el autoalojado usa el dominio de la instancia. Cada tipo de aplicación tiene su endpoint, así que compáralo con el tipo.

¿Cuántos reintentos conviene hacer ante un 429?

No hay una cifra universal. Fija un máximo de reintentos y un límite total de espera, usa retroceso exponencial con jitter aleatorio y reintenta solo 429 y 5xx. Si se activa de forma continua, reduce la concurrencia o la cuota en lugar de reintentar sin fin.

Si falla un nodo del flujo, ¿puede continuar el proceso?

Puedes evaluar el manejo de errores a nivel de nodo: reintentos, valores predeterminados o ramas de excepción. Úsalo solo en nodos cuyo fallo se pueda degradar; los errores de autenticación o de parámetros deben mostrarse directamente y no ocultarse con un valor predeterminado.

No veo el error original del upstream en los logs. ¿Qué hago?

Revisa primero si el registro de ejecución de Dify incluye un error a nivel de nodo y después consulta la consola del proveedor y los logs de la pasarela. Si el upstream solo devuelve un error genérico, llama directamente a su interfaz con la misma clave y el mismo nombre de modelo; normalmente obtendrás información más completa.

Siguiente paso

El diagnóstico de errores de Dify se basa en separar capas: primero distingue si el problema está en la API de la aplicación, en la configuración de Dify o en el modelo upstream, y después localiza por código de estado y por error de nodo. Si necesitas una entrada unificada de modelos y ver los logs de llamadas en un solo lugar, puedes registrarte en ZSQH AI Gateway; los modelos y los precios se rigen por la página de precios de modelos.

Lecturas relacionadas: