Errors, retries, and idempotency

По умолчанию упавшая нода останавливает всё: execution помечается failed, ноды после неё не выполняются. Это правильный дефолт — но n8n даёт три стратегии в Settings каждой ноды (параметр On Error).

Stop Workflow (дефолт): падение — значит падение, честно и заметно.

Continue (using regular output): ошибка проглатывается, вниз по потоку идут данные с полем error. Опасный режим: молчаливые сбои — худший сценарий интеграций; включайте только с осознанной обработкой поля error ниже по потоку.

Continue (using error output): у ноды появляется второй, красный выход; успешные items идут в обычный, ошибка — в error-ветку, где её обрабатывают явно: лог, алерт, ответ 502, деградация до значения по умолчанию.

Там же в Settings — Retry On Fail: Max Tries и Wait Between Tries (мс). Это первое средство от транзиентных ошибок: сетевой таймаут, 429 Too Many Requests, 503 у перегруженного сервиса. Но ретрай не лечит постоянные ошибки: 401 Unauthorized останется 401 и с пятой попытки, а ретраить POST без идемпотентности — значит рисковать дублями (об этом ниже).

Правило: транзиентное — ретраим, постоянное — падаем громко, ожидаемое — обрабатываем error-веткой.

Алерты о падениях не надо строить в каждом workflow копипастой — для этого есть механизм Error Workflow.

Создайте отдельный workflow, начинающийся с ноды Error Trigger. Затем в настройках БОЕВЫХ workflow (Settings → Error Workflow) укажите его. Теперь любое падение запускает error-workflow и передаёт ему контекст:

{
  "execution": {
    "id": "231",
    "url": "https://n8n.example.com/execution/231",
    "lastNodeExecuted": "Enrich lead",
    "error": { "message": "connect ECONNREFUSED 10.0.0.5:443" }
  },
  "workflow": { "id": "12", "name": "Lead intake" }
}

Дальше — нода Slack или Telegram с сообщением из этих полей: имя workflow, упавшая нода, текст ошибки и обязательно {{ $json.execution.url }} — дежурный открывает проблемный execution в один клик вместо раскопок в списке.

Один error-workflow обслуживает сколько угодно боевых. Полезно добавить в него Switch по имени workflow: критичные пайплайны — в канал с пейджингом, второстепенные — в тихий лог-канал.

Проверьте настройку до того, как она понадобится: вставьте в боевой workflow заведомо падающую ноду и убедитесь, что алерт пришёл. Про error-workflow, который никто не тестировал, узнаёшь в худший момент.

Идемпотентность — свойство обработчика давать одинаковый результат при повторной обработке того же события. В интеграциях это не опция: вебхук-провайдеры ретраят доставку при таймаутах, пользователи жмут кнопку дважды, ваш же Retry On Fail повторяет шаги. Вопрос не «придут ли дубликаты», а «что вы с ними сделаете».

Инструменты в n8n.

Первый — нода Remove Duplicates в режиме Remove Items Processed in Previous Executions: она запоминает обработанные значения ключа (например, {{ $json.body.email }} или id события) МЕЖДУ executions и молча отбрасывает повторы. Ставьте её до side effects.

Второй — проверка перед записью: GET «существует ли запись с этим external id» перед POST, или upsert-операции нод БД и CRM, где они есть.

Третий — правильный выбор ключа. Лучший ключ идемпотентности — естественный id события от источника: id платежа Stripe, id сообщения, id заявки. Генерировать свой ключ из timestamp — антипаттерн: у ретрая той же заявки будет другой timestamp.

Если внешний API поддерживает заголовок Idempotency-Key (Stripe — эталонный пример), передавайте его: тогда даже задвоенный запрос не создаст второй платёж. Общий порядок в workflow железный: сначала дедупликация, потом side effects.

Несколько паттернов, которые превращают «обычно работает» в «работает».

Экспоненциальный backoff. Встроенный Retry On Fail ждёт фиксированный интервал. Когда нужен рост паузы (щадящий режим для лежащего сервиса), соберите цикл вручную: error-ветка → Wait с expression-задержкой, растущей от номера попытки → возврат на ноду запроса, и IF-ограничитель числа попыток, чтобы цикл не стал вечным.

Маленькие workflow. Длинный пайплайн делите через Execute Sub-workflow: под-workflow можно ретраить целиком, тестировать отдельно и переиспользовать. Упавший шаг в маленьком workflow — понятная единица повтора; в монолите на тридцать нод — археология.

Retry из списка executions. Failed production executions сохраняются (проверьте в Settings workflow, что сохранение включено). После починки причины упавший execution можно перезапустить прямо из списка — Retry. Именно здесь окупается идемпотентность: повтор всего workflow безопасен.

Антипаттерны на закрепление: Continue (using regular output) без обработки поля error — молчаливая потеря данных; retry-цикл без ограничителя; ретрай неидемпотентного шага — классика с двойным списанием денег. Если шаг нельзя сделать идемпотентным, ретрай на нём должен быть выключен, а падение — громким.