Для разработчиков

Устранение ошибок

Проверить с агентом
Агент найдёт, почему workflow n8n не работает с Пачкой, проверит бота и после вашего «да» исправит настройки в Пачке
Найди, почему мой workflow в n8n не работает с Пачкой. Скачай страницу документации и делай по ней: `curl -sL https://dev.pachca.com/guides/n8n/troubleshooting.md`. Инструмент для веба отдаёт пересказ, бери его, только если curl не сработал. Если страница не открылась и так или у тебя нет инструментов Пачки, остановись и скажи.

1. Спроси текст ошибки или что не происходит, какой бот и чат участвуют и чей токен в Credentials: бота или персональный. Сам токен в чат не проси. Попроси экспорт workflow. Токены и секреты нигде не выводи.
2. Найди раздел этой ошибки, а если события не доходят, пройди все пункты раздела «Вебхук не приходит». По экспорту проверь узлы Пачки.
3. Инструментами Пачки проверь бота: адрес вебхука, события, режим новых сообщений, права токена и состоит ли бот в чате. Если чего-то не видно, скажи, что мне проверить и где.
4. Назови причину и правки: в n8n их сделаю я, в Пачке ты.
5. После моего «да» сделай правки в Пачке. Адрес вебхука у бота один: если его занял другой workflow, спроси меня. Новый токен держи в `.env`, добавленном в `.gitignore`.
6. Попроси меня запустить workflow снова и перечисли, что изменено в Пачке и как это вернуть.

Если мешают права, роль или настройки пространства, не обходи: скажи, что мешает и кто это изменит. Чего не можешь сам, например проверить настройки сервера n8n, дай мне готовыми командами.
Вставьте промпт в чат с ИИ-агентом, к которому подключена Пачка

Установка расширения

Расширение не появляется в Nodes panel

Причина: verified-ноды Пачки не подключены к instance n8n.

Решение:

  • n8n Cloud: verified-ноды включены по умолчанию. Если в поиске их нет, instance owner мог выключить пункт Verified community nodes в Instance settings в кабинете n8n Cloud (Cloud console) — попросите включить.
  • Self-hosted: проверьте переменные N8N_COMMUNITY_PACKAGES_ENABLED и N8N_VERIFIED_PACKAGES_ENABLED: у обеих должно быть значение true, оно стоит по умолчанию. Подробнее — в официальных доках n8n.
  • Старая версия n8n (до 1.94): verified-ноды не показываются в Nodes panel — обновите n8n до актуальной версии.

Нет кнопки Install node

Причина: verified-ноду может установить только instance owner или admin. Остальным участникам n8n в карточке ноды вместо кнопки Install node показывает «Please contact an administrator to install this community node» и адрес владельца instance.

Решение: запросите установку у администратора. После установки нода доступна всем участникам instance — отдельной активации для каждого участника не нужно.


Ошибки авторизации

Неверный токен (401 Unauthorized)

Узел Pachca с неверным токеном завершился ошибкой invalid_token

Признак: узел Пачки подсвечивается красным, и n8n показывает сообщение «Problem in node» с кодом invalid_token. Так узел передаёт ответ API 401 на неверный токен.

Причина: указан некорректный или просроченный Access Token.

Решение:

  1. Откройте учётные данные Пачки (Overview → вкладка Credentials или карандаш рядом с полем Credential в узле) и проверьте значение Access Token
  2. Убедитесь, что токен скопирован целиком, без лишних пробелов
  3. Сохраните Credentials кнопкой Save или нажмите Retry в баннере проверки — при ошибке создайте новый токен в Пачке
  4. Для токена бота: значение показывается только при создании, поэтому потерянный токен перевыпустите в карточке бота на вкладке API (Перевыпустить в меню токена)
  5. Для персонального токена: создайте новый на странице Интеграции → API. По умолчанию персональные токены создаёт только администратор, а сотрудник видит «Доступ к API ограничен», подробнее — в разделе Кто может создавать токены

Недостаточно прав (403 Forbidden)

Причина: операция требует более высокий уровень доступа, чем предоставляет текущий токен.

Решение:

Доступ к операциям определяют скоупы и тип токена. Убедитесь, что у токена есть нужные скоупы и что операция работает с его типом:

ОперацияТребуемые скоупы
Управление сотрудниками (User > Create/Update/Delete)users:create, users:update, users:delete (доступны администраторам и владельцам)
Журнал безопасности (Security > Get Many)audit_events:read (доступен владельцу пространства на тарифе «Корпорация»)
Экспорт сообщений (Chat > Request Export, Download Export)chat_exports:write, chat_exports:read (доступны владельцу пространства на тарифе «Корпорация»)
Все чаты и боты пространства (Chat > Get Many Workspace Chats, Bot > Get Many Workspace Bots)company_chats:read, company_bots:read (доступны владельцу пространства на тарифе «Корпорация»)
Управление тегами (Group Tag > Create/Update/Delete)group_tags:write (доступен администраторам и владельцам)
Автоматическая регистрация вебхука в Pachca Triggerprofile:read и bot_self:webhook:write (токен бота) или bots:write (персональный токен)
Отправка сообщений (Message > Create)messages:create
Чаты (Chat > Create/Update)chats:create, chats:update
Напоминания (Reminder > Create/Update/Delete)tasks:create, tasks:update, tasks:delete
Формы (Form > Create, Submit Response)views:write, только с токеном бота
Разворачивание ссылок (Message > Unfurl)link_previews:write, только с токеном бота
История и поток событий (Bot > Get Many Events, Get Stream, Remove Events)webhooks:events:read, webhooks:events:delete, только с токеном бота
Черновики (Draft) и «Важное» (Important Message)drafts:read, drafts:write, important_messages:read, important_messages:write, только с персональным токеном

Набор прав для типового сценария n8n — в разделе Наборы прав под типовые задачи, остальное — в разделе Авторизация.

403 Forbidden при публикации Pachca Trigger

Причина: узел попытался автоматически прописать Webhook URL, но у токена не хватает прав. Для токена бота нужен скоуп bot_self:webhook:write (саморегистрация методом PUTСаморегистрация вебхука бота). Для персонального токена — скоуп bots:write и доступ редактора к указанному боту (регистрация методом PUTРедактирование бота).

Текст ошибки:

Pachca rejected bot webhook self-registration (403 Forbidden).

или

Pachca rejected automatic webhook registration (403 Forbidden).

Решение:

  1. Токен бота: добавьте токену право bot_self:webhook:write — в карточке бота на вкладке API выберите Редактировать в меню токена
  2. Токен бота и заполненный Bot ID: без права profile:read узел принимает токен бота за персональный и прописывает адрес методом PUTРедактирование бота, который токену бота недоступен — добавьте токену право profile:read и очистите поле Bot ID
  3. Персональный токен: убедитесь, что владелец токена может редактировать бота — он его создатель или подходит под настройку Кто может редактировать настройки бота — и что у токена есть скоуп bots:write (Редактировать в меню токена на странице Интеграции → API). Если персональные токены создаёт только администратор, сотрудник не может изменить скоупы своего токена: используйте токен бота или персональный токен администратора
  4. Либо переключите Webhook Setup = Manual и пропишите Production URL в настройках бота самостоятельно — см. Ручной режим

400 при публикации бота со ссылками

Причина: бот получает ссылки (событие Link Shared), а адрес вебхука такому боту прописывает только администратор или владелец пространства. Токен бота и персональный токен сотрудника без этих ролей получат 400 с текстом «Изменять домены, адрес доставки и историю событий разворачивания ссылок может только администратор или владелец пространства».

Решение: переключите Webhook Setup = Manual и попросите администратора вставить Production URL в настройках бота. Либо используйте в автоматическом режиме персональный токен администратора. Подробнее — в разделе Разворачивание ссылок.

Узел не определил тип токена

Причина: в автоматическом режиме узел определяет тип токена методом GETСвой профиль, а у токена нет права profile:read. Без него и без Bot ID узел не активируется.

Текст ошибки:

The token lacks the profile:read scope, so the node cannot tell a bot token from a personal one.

Решение:

  1. Токен бота: добавьте токену право profile:read — в карточке бота на вкладке API выберите Редактировать в меню токена, затем опубликуйте workflow заново
  2. Персональный токен: заполните в узле поле Bot ID, подробнее — в разделе Автоматический режим
  3. Либо переключите Webhook Setup = Manual — см. Ручной режим

Ошибки лимитов

Превышение лимита (429 Too Many Requests)

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

Решение в n8n:

  1. Добавьте узел Wait между операциями для замедления
  2. Для массовой отправки разбейте элементы на порции узлом Loop Over Items и поставьте Wait внутри цикла
  3. Для массового чтения используйте Return All = false с ограниченным Limit
При 429 и временных ошибках сервера узел сам повторяет запрос. Правила повторов и случаи, когда узел сразу завершается ошибкой, описаны в разделе Повторные запросы.

Ошибки триггера

Вебхук не приходит

Возможные причины и решения:

  1. Событие не отмечено в карточке бота — в обоих режимах регистрации Пачка присылает только события, отмеченные на вкладке Исходящий вебхук, а новый бот не получает даже новых сообщений. Отметьте пункт по таблице из раздела Поддерживаемые события, а для New Message выберите режим «Любые сообщения» или перечислите команды.
  2. Бот не добавлен в чат — о сообщениях, реакциях, участниках чатов и видеозвонках бот узнаёт только из чатов, в которых состоит. Добавьте бота в нужный чат.
  3. Workflow не опубликован — нажмите Publish в правом верхнем углу. Неопубликованный workflow не принимает вебхуки на Production URL.
  4. URL не прописан в настройках бота — в ручном режиме узел не трогает слот вебхука бота. Проверьте, что Production URL указан адресом на вкладке Исходящий вебхук в карточке бота. В автоматическом режиме с персональным токеном убедитесь, что в узле указан верный Bot ID.
  5. Слот занят другим workflow — у бота один адрес вебхука, и события получает workflow, чей адрес записан последним. Дайте каждому workflow с Pachca Trigger своего бота или соберите события в одном workflow с событием All Events, подробнее — в разделе Как работают вебхуки в Пачке.
  6. Слот очистил тест — после тестового запуска триггера кнопкой Execute step в автоматическом режиме узел оставляет адрес вебхука пустым. Опубликуйте workflow заново, подробнее — в разделе Тестирование триггера.
  7. n8n недоступен извне — при локальной установке Пачка не может отправить вебхук на localhost. Используйте туннель или разверните n8n на сервере с публичным адресом, подробнее — в разделе Локальная разработка.
  8. Узел отклонил событие — Пачка отправляет события, а в Executions нет запусков. Так бывает, если не совпал секрет подписи, адрес отправителя не входит в Webhook Allowed IPs или неверно идут часы сервера n8n, подробнее — в разделе Событие отклонено проверкой подписи или IP.

Событие отклонено проверкой подписи или IP

Признак: Пачка отправляет события, а в Executions нет запусков. Узел отклоняет такой запрос без записи в журнал, и workflow не запускается.

Возможные причины и решения:

  1. Секрет не совпадает — значение поля Webhook Signing Secret в Credentials отличается от секрета бота в Пачке. Секрет меняется, например, когда вебхук удаляют кнопкой Удалить вебхук. Скопируйте поле Signing secret с вкладки Исходящий вебхук в карточке бота и вставьте его в поле Webhook Signing Secret в Credentials.
  2. Адрес отправителя не в списке — если поле Webhook Allowed IPs в Credentials заполнено, узел принимает события только с перечисленных адресов. Сверьте список с адресами Пачки из раздела Безопасность или очистите поле.
  3. Неверно идут часы сервера n8n — узел отклоняет событие, если его метка webhook_timestamp старше пяти минут по часам сервера или опережает их больше чем на минуту. Включите на сервере n8n синхронизацию времени.

Ошибки данных

Entity ID не найден

Причина: указан несуществующий ID чата, сотрудника или сообщения.

Решение:

  • Для чатов: выберите чат в режиме From list или найдите его операцией Search > Get Many Chats
  • Для сотрудников: выберите сотрудника в режиме From list или найдите его операцией Search > Get Many Users
  • Для сообщений: убедитесь, что сообщение не было удалено

Где взять идентификаторы вручную — в разделе Где взять идентификаторы.

Бот не может отправить сообщение

Причина: бот не является участником целевого чата.

Решение: добавьте бота в чат. Бот может отправлять сообщения только в те чаты, в которых он состоит.


Ошибки форм

Форма не открывается

Причина: форму по trigger_id из события button_pressed нужно открыть методом POSTОткрытие представления в первые 3 секунды, позже форма не откроется. Подробнее — в разделе Сроки ответа.

Решение:

  1. Убедитесь, что узел Form > Create стоит сразу после триггера, без долгих операций между ними
  2. Не используйте узел Wait между получением trigger_id и открытием формы
  3. Дополнительную логику выполняйте после отправки формы

Подробнее о формах — в документации форм.


Ошибки пагинации

Возвращаются не все данные

Причина: API возвращает данные постранично. Если Return All выключен, вы получаете только первую страницу (по умолчанию до 50 записей).

Решение:

  1. Включите Return All = true в настройках узла — n8n автоматически пройдёт по всем страницам через cursor-based пагинацию
  2. Если нужен ограниченный набор — используйте Return All = false и укажите нужное число в поле Limit
  3. Для больших объёмов данных учитывайте лимиты API — при Return All n8n делает несколько запросов последовательно

Общие практики тестирования и отладки — Retry On Fail, Error Trigger workflow, Execute step, проверка Credentials — собраны в разделе Тестирование.