Dead-letter queue в n8n: runbook для failed items и replay ¶

Обновлено: 2026-05-29

Intent: runbook dead-letter queue pattern: failed items, replay, quarantine, manual review и защита от бесконечных retry в n8n
H1: Dead-letter queue в n8n: как хранить failed items и делать replay без дублей
Schema: TechArticle, HowTo, FAQPage, BreadcrumbList
Old word count: 661
New word count: 726

Короткий ответ ¶

В n8n dead-letter queue чаще реализуют как паттерн, а не как одну волшебную кнопку: failed item нужно сохранить в отдельный журнал с причиной, retry count, external ID и payload snapshot, а затем переигрывать отдельным replay workflow. Главное — не смешивать основной поток, бесконечные retry и ручной разбор. Если элемент падает несколько раз, он должен уходить в quarantine, а не снова атаковать API или создавать дубли.

Когда нужен DLQ-паттерн ¶

Dead-letter queue нужен, когда процесс нельзя просто “упасть и забыть”. Это особенно важно для:

• платежных уведомлений;
• CRM-лидов;
• заказов интернет-магазина;
• тикетов поддержки;
• email/SMS/Telegram рассылок;
• интеграций с нестабильным внешним API;
• AI/RAG-веток, где часть ответов требует ручной проверки.

Без DLQ failed items теряются в истории executions или переигрываются вручную из чата. Это плохо масштабируется и почти всегда приводит к дублям.

1. Что считать dead-letter ¶

Не каждая ошибка должна сразу уходить в DLQ. Разделите ошибки на временные и постоянные.

Правило простое: если ошибка не исправится повторной попыткой или уже была несколько раз, item должен выйти из основного потока.

2. Минимальная структура DLQ ¶

DLQ может быть таблицей в Postgres, Google Sheets, Airtable, Supabase, внутренней CRM-таблицей или отдельным queue/storage. Главное — стабильная схема.

Минимальные поля:

id
created_at
workflow_name
execution_id
node_name
external_event_id
business_object_type
business_object_id
error_type
error_message
retry_count
payload_snapshot
status: new | retrying | resolved | skipped | escalated
owner
last_attempt_at
resolution_note

Не храните секреты, access tokens и лишние персональные данные в DLQ. Payload snapshot должен быть достаточным для replay, но не превращаться в незащищённый архив всех данных.

3. Как встроить DLQ в workflow ¶

Базовая архитектура:

1. Main workflow получает событие.
2. Проверяет external_event_id на дубли.
3. Выполняет основную операцию.
4. При временной ошибке делает limited retry.
5. При постоянной ошибке пишет item в DLQ.
6. Error workflow отправляет уведомление только при нужной severity.
7. Replay workflow забирает items со статусом new или retrying.

Для node-level обработки используйте отдельную ветку ошибок или явную проверку результата. Важнее всего не потерять ID и контекст: без них replay становится угадыванием.

4. Replay workflow ¶

Replay должен быть отдельным workflow с ограничениями.

Правила replay:

• принимать список DLQ IDs, а не “всё подряд”;
• обрабатывать маленькими batch;
• перед повторной операцией делать status check;
• использовать idempotency key;
• увеличивать retry_count;
• менять status только после подтверждения;
• писать resolution_note.

Плохой replay — снова отправить все failed payloads в production API без проверки. Хороший replay — понять текущее состояние объекта и выполнить только недостающую операцию.

5. Quarantine и manual review ¶

Если item три раза упал на одном и том же месте, он не должен бесконечно повторяться. Переведите его в escalated или manual_review.

Примеры quarantine-сценариев:

• клиентский email отсутствует, но CRM требует email;
• payment status у провайдера не совпадает с internal order status;
• AI output не прошёл JSON Schema;
• внешний API вернул conflict, но lookup не нашёл объект;
• webhook payload пришёл от неизвестного tenant.

Manual review должен иметь владельца и срок реакции. Иначе DLQ превращается в кладбище ошибок.

6. Метрики и алерты ¶

DLQ полезен только если за ним смотрят. Минимальные метрики:

• количество новых items;
• items старше 1 часа/1 дня;
• retry count > 3;
• top error types;
• top workflows by DLQ count;
• resolved/skipped ratio;
• среднее время до resolution.

Алерт нужен не на каждый failed item, а на рост очереди, S1/S2-процессы и items старше SLA.

FAQ ¶

Есть ли в n8n отдельная встроенная DLQ для всех workflow?
На практике для бизнес-процессов чаще проектируют собственный DLQ-паттерн: журнал failed items, replay workflow и правила quarantine.

Чем DLQ отличается от error workflow?
Error workflow уведомляет и помогает triage. DLQ хранит конкретные failed items для повторной обработки и ручного разбора.

Нужно ли хранить полный payload?
Только если это безопасно и необходимо. Лучше хранить ключевые ID, нормализованный payload и ссылку на защищённый источник.

Когда item можно считать resolved?
Только после проверки внешнего состояния: объект создан, статус обновлён, уведомление отправлено или бизнес-решение зафиксировано.

{
  "request_id": "req_demo_001",
  "prompt_version": "2026-05-29",
  "input": "краткое нормализованное сообщение пользователя",
  "allowed_actions": ["read", "draft", "classify"],
  "forbidden_actions": ["send_without_review", "change_payment"],
  "expected_output": {
    "intent": "technical|support|sales|unknown",
    "confidence": 0.0,
    "needs_human_review": true,
    "sources": []
  }
}