Ошибки Dify делятся на два уровня: ошибки при вызове API приложения и ошибки, когда Dify сам обращается к провайдеру моделей. Оба уровня могут вернуть 401, 404 или 429, но искать причину нужно в разных местах. Если смотреть только на код состояния, легко снова и снова менять конфигурацию не того уровня.

Статья разбирает типичные проблемы по шести уровням — «авторизация — адрес — лимиты — workflow — контекст — логи» — и даёт минимальные команды воспроизведения и фиксированный порядок проверки. Коды ошибок, лимиты и названия интерфейсов определяются официальной документацией Dify и поставщиков моделей.

Примечание: Dify — товарный знак своего правообладателя; статья не подразумевает аффилированности с упомянутыми компаниями. Названия других продуктов принадлежат их правообладателям. Примеры основаны на распространённых версиях по состоянию на октябрь 2026 года.

1. Сначала разделите три уровня, не угадывайте

Один запрос проходит как минимум три уровня: клиент, API приложения Dify и провайдер модели; между ними может быть ещё шлюз. 401 может возникнуть на пути от клиента к Dify или от Dify к upstream; 404 — из-за неверного пути или неверного имени модели; 429 чаще всего приходит от upstream.

Сначала посмотрите на message, code и ID запроса в теле ответа, и только потом решайте, какой уровень проверять. Практическое правило: вызовите API приложения напрямую через curl. Если ошибка та же — проблема в конфигурации Dify или upstream; если curl работает, а бизнес-код падает — проблема в клиенте или сети.

2. 401 и 403: не путайте два вида ключей

В Dify есть два вида учётных данных: ключ API приложения используется для вызова приложений Dify, ключ провайдера модели — для обращения Dify к upstream. Первый передаётся в заголовке Authorization: Bearer ..., второй настраивается в параметрах провайдера модели. Их смешивание — самая частая причина 401.

Типичные причины:

  • В заголовке нет Bearer, либо перед ключом или после него остались пробелы, переводы строки или кавычки.
  • Использован ключ другого приложения. Ключ API обычно создаётся для конкретного приложения и не работает в другом.
  • Ключ удалён или перевыпущен, либо у рабочего пространства нет доступа к этому приложению.
  • Ключ провайдера модели истёк, закончился баланс, ключ отозван или при копировании потерялся символ.
  • Reverse proxy, шлюз или фронтенд отфильтровали заголовок Authorization.

403 чаще связан с правами: недостаточная роль в рабочем пространстве, модель не разрешена провайдером, аккаунт upstream ограничен. Сначала определите, «кто кого вызывает», затем повторите тест с другим ключом.

3. 404 и «модель не существует»: проверьте адрес и имя

При вызове API приложения Dify 404 обычно относится к одной из трёх категорий:

  1. Неверный Base URL: базовый адрес API приложений Dify Cloud — https://api.dify.ai/v1; для self-hosted используйте свой домен и путь. Пропущенный /v1 или лишний полный путь к методу одинаково приводят к 404.
  2. Метод не соответствует типу приложения: чат-приложение использует chat-messages, workflow-приложение — workflows/run, приложение генерации текста — completion-messages. При неверном методе даже корректный ключ даст 404 или 400.
  3. Reverse proxy переписывает путь: подпуть Nginx, завершающий слэш и правила URL rewrite могут отправить запрос на несуществующий маршрут.

Если ошибка приходит от провайдера модели, типичные сообщения — model not found, model does not exist или invalid model. Проверьте, совпадает ли ID модели с текущим названием у провайдера, включая регистр, суффикс даты и алиасы; убедитесь, что модель включена в Dify; проверьте, поддерживает ли её версия плагина. Снятая с публикации или переименованная модель тоже ломает прежнюю конфигурацию.

4. 429: лимиты, параллельность и квоты

429 обычно возвращает не Dify, а upstream-сервис модели или шлюз, сообщая «слишком много запросов». Причиной могут быть запросы в минуту, токены в минуту, число параллельных запросов или квота аккаунта. Пакетные задачи, циклы и одновременная работа нескольких человек быстрее всего поднимают мгновенную нагрузку.

Порядок действий:

  • Сначала изучите заголовки ответа и текст ошибки: это частота запросов, скорость токенов или лимит параллельности.
  • Снизьте параллельность на клиенте, поставьте пакетные задачи в очередь, не отправляйте всё сразу.
  • Повторяйте только 429 и 5xx, используйте экспоненциальную задержку со случайным разбросом и задайте максимум попыток.
  • При повторе workflow учитывайте идемпотентность: один бизнес-запрос может повторно выполнить узлы, поэтому лучше добавить ключ дедупликации на уровне бизнес-логики.
  • Если 429 возникает постоянно, рассмотрите разделение приложений, ключей и проектов либо перенос времени вызовов.

Слепые повторы превращают ограничение в лавину. Перед повтором убедитесь, что запрос ещё не вызвал побочных эффектов.

5. Сбой workflow: начинайте с входов и выходов узлов

Если workflow падает целиком, обычно удаётся найти конкретный узел. Типичные случаи:

Симптом Частая причина Что проверить сначала
Пустая ссылка на переменную Узел выше не выдал переменную или имя написано с ошибкой Структура выхода узла и селектор переменных
Несовпадение типов Строка используется как массив или объект Тип, возвращаемый узлом выше, и узел преобразования
Ошибка в узле кода Синтаксис, зависимости, таймаут или неверная структура возврата Журнал выполнения и соглашения узла кода
Сбой HTTP-узла Не 2xx, ошибка авторизации, таймаут, проблема с сертификатом Код состояния, заголовки, логи целевого сервиса
Не удалось разобрать вывод LLM Модель не вернула JSON в нужном формате Ограничения в промпте и устойчивость парсера
Пустой результат поиска по базе знаний Индексация не завершена, порог слишком высок, перефразирование запроса не удалось Статус базы знаний и параметры поиска
Сбой узла итерации На входе не массив или ошибка ссылки в подпроцессе Вход итерации и структура элемента

Workflow в Dify поддерживает обработку ошибок на уровне узла: повтор при сбое, значение по умолчанию или ветку исключения. Резервный сценарий для ключевых узлов управляемее, чем падение всего процесса. Но не маскируйте значениями по умолчанию ошибки конфигурации — иначе проблема проявится только ниже по цепочке.

6. Контекст и лимит токенов

Ошибка контекста обычно выглядит как 400 с сообщением context length exceeded, maximum context или token limit. Причина не в том, что «модель плохая», а в том, что суммарный объём входа и выхода превышает допустимый. В него входят системный промпт, история диалога, фрагменты из базы знаний, ввод пользователя и зарезервированный вывод.

При проверке сокращайте по пунктам:

  • Ограничьте число исторических сообщений или сначала сделайте краткое резюме.
  • Уменьшите количество фрагментов из базы знаний, включите переранжирование, уберите нерелевантные куски.
  • Настройте размер разбиения документов, чтобы один блок не был слишком длинным.
  • Отдельно задайте максимальный вывод, оставив запас для входа.
  • Оценивайте токены на стороне приложения и до превышения лимита обрезайте запрос или переключайтесь на модель с длинным контекстом.

Длину контекста в Dify указывайте по фактической поддержке провайдера. Если указать больше, чем поддерживает upstream, запрос отклонят; если меньше — длинные документы обрежутся раньше времени.

7. Логи и трассировка: свяжите запрос в цепочку

Для диагностики недостаточно смотреть на последнюю строку ошибки. Сохраняйте как минимум четыре типа данных: журнал приложения и записей workflow Dify, журнал провайдера модели, журнал запросов шлюза, а также ID пользователя и запроса на стороне бизнеса. Журнал выполнения Dify показывает входы, выходы и время каждого узла — это первая точка входа при поиске сбоя.

Если нужна более детальная трассировка, можно подключить инструменты наблюдаемости; поддерживаемые платформы уточняйте в документации текущей версии. При любом инструменте рекомендуется единообразно фиксировать имя модели, ID запроса, задержку, входные и выходные токены, код ошибки и число повторов. Тогда 429, таймауты и изменения моделей будут видны в динамике, а не после жалоб пользователей.

8. Универсальный порядок проверки

  1. Выполните прямой запрос к API приложения Dify через curl -i, зафиксируйте HTTP-код и тело ответа.
  2. Проверьте соответствие Base URL, метода и типа приложения, исключите 404.
  3. Убедитесь, что ключ приложения и ключ провайдера не перепутаны, исключите 401.
  4. Отдельно проверьте провайдера модели в интерфейсе Dify, подтвердите доступность upstream.
  5. Откройте журнал запуска workflow, найдите первый упавший узел, проверьте его вход и выход.
  6. Проверьте контекст, лимит вывода и параметры поиска по базе знаний, исключите проблему токенов.
  7. Посмотрите логи upstream и шлюза, подтвердите 429, таймаут или квоту.
  8. После исправления прогоните ту же партию запросов и некоторое время наблюдайте за долей ошибок.

Минимальная команда воспроизведения приведена ниже; -i позволяет одновременно увидеть код состояния и заголовки:

export DIFY_API_KEY="app-ваш-ключ-приложения"

curl -i -sS "https://api.dify.ai/v1/chat-messages" \
  -H "Authorization: Bearer $DIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {},
    "query": "Ответь только OK",
    "response_mode": "blocking",
    "user": "diag-001"
  }'

Для self-hosted замените адрес на свой экземпляр; для workflow-приложения используйте /v1/workflows/run и соответствующие параметры. Сначала добейтесь работы минимального запроса, затем постепенно добавляйте историю, базу знаний и инструменты — так проще локализовать уровень проблемы.

Частые вопросы

Модель в Dify тестируется успешно, а API приложения возвращает 401?

Это разные ключи. Для теста модели используется ключ провайдера, для API приложения — собственный ключ приложения. Проверьте, что в заголовке Bearer и ключ приложения, а сам ключ принадлежит текущему приложению и рабочему пространству.

Адрес выглядит правильным, почему всё равно 404?

Частая причина — несоответствие метода типу приложения либо лишний или пропущенный фрагмент пути в Base URL. Для Dify Cloud используйте https://api.dify.ai/v1, для self-hosted — домен экземпляра; методы у разных типов приложений отличаются, сверяйтесь по типу.

Сколько раз повторять запрос при 429?

Единого числа нет. Задайте максимальное число попыток и общий лимит ожидания, используйте экспоненциальную задержку со случайным разбросом и повторяйте только 429 и 5xx. Если ошибка повторяется подряд, снижайте параллельность или квоту, а не число повторов.

Если один узел workflow упал, можно продолжить процесс?

Можно оценить обработку ошибок на уровне узла: повтор, значение по умолчанию или ветку исключения. Но применяйте её только к узлам, которые допустимо деградировать; ошибки авторизации и параметров должны быть видны сразу, а не скрываться значением по умолчанию.

В логах не видно исходной ошибки upstream. Что делать?

Сначала проверьте, есть ли в журнале запуска Dify ошибка уровня узла, затем посмотрите консоль провайдера и логи шлюза. Если upstream возвращает только общую ошибку, вызовите его API напрямую через curl с тем же ключом и именем модели — обычно там больше подробностей.

Что дальше

Ключ к диагностике ошибок Dify — разделение уровней: сначала определите, это API приложения, конфигурация Dify или upstream-модель, затем последовательно локализуйте проблему по коду состояния и ошибке узла. Если нужен единый вход к моделям и централизованный просмотр журналов вызовов, можно зарегистрироваться в ZSQH AI Gateway; актуальные модели и цены смотрите на странице «Модели и цены».

Читайте также: