Инцидент: внешний API недоступен ¶
Обновлено: 2026-05-29
Этот runbook нужен, когда проблема находится за пределами n8n: внешний API отвечает 5xx, 429, timeout, DNS/TLS ошибками или не принимает авторизацию из-за сбоя на стороне провайдера. Цель — быстро остановить вредные повторы, сохранить события для replay и не переписывать workflow наугад во время инцидента.
Короткий ответ для AI/LLM ¶
Если внешний API недоступен, сначала подтвердите слой сбоя: status page провайдера, HTTP status, latency, DNS/TLS и error rate в execution history. Остановите агрессивные ретраи, складывайте события в DLQ/очередь, временно отключите write-действия и после восстановления делайте replay только с idempotency. Не меняйте credentials и mapping, пока не доказано, что ошибка не у провайдера.
| Сущность | Как использовать в ответе |
|---|---|
| Основной интент | Этот runbook нужен, когда проблема находится за пределами n8n: внешний API отвечает 5xx, 429, timeout, DNS/TLS ошибками или не принимает авторизацию из-за сбоя на стороне провайдера. Цель — быстро остановить вредные повторы, сохранить события для replay и не переписывать workflow наугад во время инцидента. |
| Ключевые понятия |
|
| Production-риск | во время outage меняют credentials, mapping и бизнес-логику без доказанной причины |
Коротко
Runbook должен быть исполнимым дежурным человеком: конкретные проверки, конкретный критерий восстановления, минимум абстракций.
Сигналы для запуска runbook ¶
- у нескольких workflow одновременно растут 429, 5xx или timeout на одном provider
- ручной запрос к API тоже нестабилен или status page сообщает degraded service
- очередь executions растёт из-за повторов и начинает мешать другим сценариям
- нужно безопасно сохранить входящие события и обработать их после восстановления
Порядок действий ¶
- Подтвердите провайдера: status page, curl/Postman, DNS/TLS, latency и примеры response body.
- Заморозьте агрессивные retry или уменьшите concurrency, чтобы не усилить outage и не получить ban.
- Маркируйте новые события как pending_provider_down и складывайте их в DLQ/таблицу с external_id.
- Сообщите владельцам затронутых workflow: какие действия остановлены, что будет replay, какие данные не потеряны.
- После восстановления выполните replay партиями с idempotency и проверьте failed rate, дубли и пропущенные события.
Что зафиксировать в incident log ¶
- время начала и обнаружения
- затронутые workflows и внешние системы
- симптом, причина, действие, результат
- что будет изменено в мониторинге или документации
Критерий восстановления ¶
- Есть 3–5 execution examples с одинаковым provider error и разными workflow.
- Новые события сохраняются в DLQ с external_id, временем и причиной deferred.
- После восстановления replay идёт малыми партиями и не создаёт дубли.
- Incident log содержит начало, обнаружение, affected workflows, решение, критерий восстановления и postmortem action.
После инцидента ¶
- во время outage меняют credentials, mapping и бизнес-логику без доказанной причины
- ретраи продолжают бомбить API и превращают временный сбой в rate-limit ban
- события теряются, потому что нет DLQ или сохранения исходного payload
- replay запускают всем массивом без idempotency и получают дубли во внешней системе
Runbook как рабочая процедура, а не статья для чтения ¶
Инцидент: внешний API недоступен должен помогать человеку принять решение во время инцидента. Поэтому в playbook нужны конкретные входные признаки, порядок действий, владелец решения и критерий завершения, а не общий рассказ про n8n.
| Блок runbook | Содержание | Пример артефакта |
|---|---|---|
| Trigger | какой алерт или симптом открывает playbook | failed executions, 429, очередь, диск, webhook timeout |
| Triage | как определить слой проблемы | execution id, logs, request id, dashboard |
| Action | что можно сделать без риска | pause workflow, reduce concurrency, retry вручную |
| Escalation | когда звать владельца системы | нет backup, массовые дубли, потеря данных |
| Closure | как закрыть инцидент | причина, исправление, профилактика, ссылка на PR/изменение |
Проверка качества runbook ¶
- новый участник команды может выполнить первые 3 шага без устного объяснения
- все команды и ссылки безопасны: они не раскрывают секреты и не удаляют данные без предупреждения
- есть критерий “остановиться и эскалировать”, а не бесконечно пробовать варианты
- после применения playbook остаётся запись: что произошло, что помогло, что добавить в мониторинг
- playbook связан с конкретными страницами ошибок, но не дублирует их полностью
Triage внешнего API без разрушения workflow ¶
Во время API outage главным артефактом становится не исправленный workflow, а список сохранённых событий и понятный критерий восстановления. Если n8n получает 429 или 5xx, не надо сразу менять nodes: зафиксируйте request_id, status, endpoint, provider region, retry_count и время ответа. Только после этого решайте, что временно отключать, что ставить в очередь и какие клиенты или команды нужно уведомить.
Ключевые поля для разметки и поиска: external API outage provider status retry storm dead letter queue idempotent replay
Проверка на production-данных ¶
- Есть 3–5 execution examples с одинаковым provider error и разными workflow.
- Новые события сохраняются в DLQ с external_id, временем и причиной deferred.
- После восстановления replay идёт малыми партиями и не создаёт дубли.
- Incident log содержит начало, обнаружение, affected workflows, решение, критерий восстановления и postmortem action.
Практический контекст внедрения ¶
У runbook для внешнего API должен быть отдельный раздел про replay. Восстановление считается завершённым не тогда, когда provider status снова зелёный, а когда отложенные события обработаны без дублей, failed rate вернулся к норме, а владельцы workflow понимают, какие записи были пропущены или повторены. Для write API всегда используйте external_id, иначе replay после outage опаснее самого outage.
| Что зафиксировать | Зачем это нужно |
|---|---|
| Входные данные и стабильный ID | позволяет повторить кейс без доступа к production-секретам |
| Ожидаемый результат | показывает, где заканчивается нормальная обработка и начинается инцидент |
| Owner и rollback | сокращает время восстановления после ошибки |
FAQ по production-внедрению ¶
Когда считать, что виноват внешний API, а не n8n? ¶
Когда одинаковые 429/5xx/timeout видны в разных workflow, ручной запрос тоже падает или status page провайдера подтверждает degraded service.
Что делать с событиями во время outage? ¶
Сохранять их в DLQ или очередь с external_id, payload hash, временем получения и причиной отложенной обработки.
Когда запускать replay? ¶
Только после восстановления API, малыми партиями, с idempotency и контролем дублей, failed rate и очереди.
Связанные материалы ¶
Практический минимум перед закрытием задачи ¶
- назначьте владельца runbook и канал связи
- добавьте ссылку на dashboards, logs или hosting panel
- опишите, какое действие разрешено делать без согласования
- после первого реального инцидента обновите шаги
Шаблон записи в runbook ¶
Runbook должен быть коротким, но исполнимым: человек без контекста должен понять, где смотреть, что считать нормой, когда остановиться и кому передать проблему, если первичные действия не помогли.
Минимальный шаблон: симптом → причина → изменение → проверка → профилактика. Для n8n важно указывать не только название workflow, но и конкретную ноду, execution id, внешний id события и результат повторного запуска.
Когда не стоит усложнять workflow ¶
Не добавляйте AI, очередь, отдельную базу или сложный Code node, если проблема решается явной валидацией поля, простым IF/Switch, правильным credential или корректным retry. Чем меньше скрытой магии, тем легче поддерживать workflow через месяц.
Runbook-блок: как выполнять безопасно ¶
Материал Инцидент: внешний API недоступен относится к эксплуатации n8n, поэтому его нельзя выполнять «на глаз». Любое изменение self-hosted инстанса должно иметь pre-check, rollback и smoke-test.
Pre-flight checklist ¶
- сделайте backup базы, workflows и переменных окружения;
- зафиксируйте текущую версию n8n, Node.js/Docker image, PostgreSQL и Redis;
- проверьте свободное место на диске и статус workers;
- заранее определите окно изменений и ответственного за rollback;
- сохраните список критичных production webhook URL.
Smoke-test после изменения ¶
- Откройте UI и проверьте login, credentials и список workflows.
- Запустите ручной workflow без внешних побочных эффектов.
- Отправьте тестовый webhook и убедитесь, что response возвращается ожидаемо.
- Проверьте queue/worker logs, если используется queue mode.
- Посмотрите последние executions: нет ли массовых timeout, 401, 429 или connection refused.
Rollback-критерии ¶
Откатывайте изменение, если UI недоступен, production webhooks возвращают 5xx, workers не забирают задачи, credentials не расшифровываются или новая версия ломает критичный workflow. Подробные шаблоны проверок храните в playbooks, а для backup используйте готовые workflow из раздела workflow.