Когда воркфлоу n8n падает, на холсте обычно видна лишь красная строка. Полезная информация прячется в истории запусков: HTTP-статус, код ошибки от upstream и фактический адрес, куда ушёл запрос. Получив эти три вещи, большинство ошибок можно локализовать за несколько минут.

Разберём по типам: 401 и 403 относятся к учётным данным и правам, 404 чаще всего означает Base URL или имя модели, 429 — лимиты и квоты, тайм-аут узла и сбой воркфлоу требуют проверки конфигурации и среды, отдельно — ошибка разбора JSON. В конце приведён фиксированный порядок диагностики, который команда может оформить как собственный runbook.

Примечание: n8n и OpenAI — товарные знаки их правообладателей; материал не связан с указанными компаниями. Имена моделей и цены — на странице цены на модели, поля узлов — в документации вашей версии.

1. Сначала история запусков, а не догадки

Откройте слева раздел Executions, отфильтруйте Failed, войдите в неудачный запуск и просмотрите вход, выход и детали ошибки по каждому узлу. Зафиксируйте четыре вещи: имя узла, HTTP-статус, код ошибки upstream и ID запроса, если он есть. Они показывают, в чём проблема — в конфигурации n8n, сетевом маршруте или сервисе upstream.

Для первичной классификации используйте таблицу:

Статус Обычное значение Что проверить первым
401 Не аутентифицирован или ключ недействителен Выбраны ли учётные данные, не истёк ли ключ
403 Аутентификация есть, прав нет Права на модель, белый список IP
404 Адрес или модель не существуют Путь Base URL, написание имени модели
429 Лимит или квота исчерпаны Параллелизм, стратегия повторов, квота аккаунта
400 Некорректные параметры запроса Имена полей, длина контекста, формат сообщений
5xx Временный сбой upstream Повторить позже, проверить статус сервиса

2. 401: ключ может быть верным и всё равно не работать

401 не всегда означает «неверный ключ». Частые причины: учётные данные созданы, но не выбраны в узле воркфлоу; при копировании попали пробел или перевод строки; тестовый ключ отключён; в команде один экземпляр и несколько наборов учётных данных, а узел ссылается на другой; самостоятельный экземпляр сменил N8N_ENCRYPTION_KEY, и старые учётные данные не расшифровываются.

Порядок простой: заново выберите учётные данные, вставьте ключ заново, сохраните и запустите только этот узел. Если ошибка осталась, выполните curl на машине, сопоставимой со средой n8n:

curl -i https://адрес-вашего-шлюза/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"имя-вашей-модели","messages":[{"role":"user","content":"Ответь только OK"}]}'

Если curl успешен, а n8n — нет, проблема в учётных данных или конфигурации узла; если оба варианта падают, дело в ключе, шлюзе или сети. Не записывайте ключ в узел Code, JSON воркфлоу или поля заметок: такие файлы легко экспортируются и передаются.

3. 404: Base URL и имя модели делят ответственность пополам

В учётных данных типа OpenAI Base URL обычно указывают до /v1, а узел сам добавляет /chat/completions. Если записать полный путь, получится адрес вроде /v1/chat/completions/chat/completions и ответ 404. Наоборот, узлу HTTP Request нужен полный URL, одного домена недостаточно.

Вторая половина 404 связана с именем модели. OpenAI-совместимые сервисы часто отвечают model_not_found, что может прийти и как 404, и внутри 400. Проверьте три вещи: регистр имени, наличие суффикса даты и то, используется на шлюзе псевдоним или исходное имя. Надёжнее всего запросить /v1/models и брать только имена из ответа.

Ещё несколько деталей: лишний слэш в конце Base URL даёт двойной слэш; если шлюз размещён под подпутём обратного прокси, префикс нельзя опускать; после переключения тестовой и продакшен-среды адрес иногда забывают синхронизировать.

4. 429: лимиты не решаются одними повторами

429 означает, что запрос ограничен. Типичные условия: превышено число запросов или токенов в минуту, превышен параллелизм, исчерпана квота или баланс аккаунта. Если в заголовках есть Retry-After, следуйте ему, а не отправляйте запрос немедленно.

В настройках узла n8n можно включить Retry On Fail, задать 2–3 попытки и увеличивающуюся паузу. Но повторы гасят только кратковременные сбои и не устраняют устойчивое превышение. Для пакетных задач снижайте параллелизм, обрабатывайте данные через Split In Batches или Loop Over Items с паузами между пакетами; распределяйте расписания, чтобы они не совпадали; при отладке не запускайте процесс на полном наборе данных.

5. Тайм-аут узла и сбой воркфлоу

Сначала разделите уровни: тайм-аут самого узла HTTP Request, тайм-аут воркфлоу, тайм-аут обратного прокси или балансировщика, время генерации модели. Срабатывание любого уровня приводит к сбою, но формулировки ошибок обычно различаются.

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

Настройте и стратегию на уровне узла: для пакетных задач используйте On Error с продолжением и сохранением ошибочных элементов, для критичных записей — остановку воркфлоу. Добавьте Error Workflow, который отправляет ID запуска, имя узла и краткое описание входа в чат или на почту. Сбой не страшен — страшно отсутствие записи о нём.

6. Ошибка разбора JSON: модель вернула не JSON

Типичная ошибка — JSON parameter needs to be valid JSON или исключение JSON.parse в узле Code. Причина обычно в том, что модель добавила пояснение или Markdown-обёртку вокруг JSON, а типы полей не совпали с договорённостью.

Сначала исправьте на стороне upstream: в промпте явно укажите «выводи только JSON, без блоков кода», опишите поля и типы; если шлюз или модель поддерживает структурированный вывод, используйте его. На downstream всё равно нужен защитный разбор, например в узле 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 } }];
}

При ошибке разбора не отбрасывайте данные молча: сохраните исходный текст в таблицу исключений и выборочно проверьте несколько записей вручную — так часто находятся проблемы промпта или ограничения модели.

7. Повторяемый порядок диагностики

  1. Определите масштаб: падает одна запись, весь пакет или весь воркфлоу.
  2. Воспроизведите запрос через curl в той же сети, что и n8n, исключив влияние конфигурации узла.
  3. Сравните фактический URL, заголовки и тело запроса n8n — прежде всего склейку Base URL.
  4. Запросите /v1/models и сверьте имя модели, регистр и суффикс.
  5. Зафиксируйте статус и код ошибки: 401, 403 и 404 не повторяйте; 429, 5xx и тайм-ауты имеют смысл повторять.
  6. Проверьте тайм-ауты, параллелизм и размер пакета, затем решайте, менять ли параметры повторов.
  7. Запишите вывод в командный runbook с примерами ошибок и действиями по исправлению.

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

n8n отвечает 401, а curl работает — где искать проблему?

Проверьте, не выбраны ли в узле неверные учётные данные, нет ли пробелов или переводов строк в ключе, не менялся ли ключ шифрования экземпляра. Можно вручную добавить заголовок Authorization в узле HTTP Request и сравнить — так видно, дело в разборе учётных данных или в построении запроса.

404 всегда означает ошибку Base URL?

Нет. Лишний путь в адресе, отсутствие /v1, потеря префикса обратного прокси дают 404; отсутствующая модель тоже может вернуть 404. Сначала подтвердите существование модели через /v1/models, затем проверяйте уровни адреса.

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

Обычно 2–3 раза с увеличивающейся паузой и соблюдением Retry-After. Устойчивый 429 означает, что параллелизм или квота уже превышены; дальнейшие повторы только усиливают перегрузку — уменьшайте пакет или разносите запуски по времени.

Воркфлоу завершился успешно, но результат пустой — что проверять?

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

Какие сетевые проблемы важны для самостоятельного n8n?

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

Что дальше

Общий принцип диагностики: сначала доказательства, потом изменение конфигурации; сначала адрес и учётные данные, потом повторы и тайм-ауты. Если нужен единый OpenAI-совместимый вход, отдельные виртуальные ключи и учёт расхода, зарегистрируйтесь в ZSQH AI Gateway; модели и цены — на странице цены на модели.

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