Документация › Справочники › Коды ошибок
Коды ошибок и состояния
Справочник кодов и состояний, которые встречаются в системе: почему бот не отвечает, какие ошибки отдаёт API, что значат состояния канала. Диагностика по шагам: в Бот не отвечает.
⏱ 7 мин · 👤 справочник · 🟢 live
Доступ к ответу бота (eligibility)
Почему бот может не отвечать (проверка перед ответом):
| Код | HTTP | Значение |
|---|---|---|
PROJECT_NOT_ACTIVE | 403 | проект в черновике |
ACCOUNT_BANNED | 403 | аккаунт заблокирован |
INSUFFICIENT_BALANCE | 402 | пустой баланс |
NO_SUBSCRIPTION | 402 | нет подписки |
SUBSCRIPTION_EXPIRED | 402 | подписка истекла |
TRIAL_EXPIRED | 402 | пробный период WhatsApp кончился (14 дней с подключения) |
PROJECT_NOT_FOUND | 404 | проект не найден |
→ Бот не отвечает, диагностика
Причины автопаузы ИИ (ai_off_reason)
Бот молчит в диалоге намеренно. Важно: бот никогда не решает остановиться сам, пауза всегда ставится либо функцией, либо оператором, либо классификацией «это не новый лид», либо технической/защитной причиной. В колонке «снимается», сама ли уйдёт пауза или только ручным тумблером AI в шапке диалога.
| Причина | Значение | Снимается |
|---|---|---|
lead_handoff | функция с галкой «Завершать диалог после выполнения» успешно отработала (передача заявки специалисту) | вручную |
client_stop | клиент попросил не писать, функция stop_dialog | вручную |
operator_joined_chat | оператор начал писать в идущий AI-диалог | вручную |
chat_started_by_operator | диалог начат вручную (оператор написал первым) | вручную |
operator_manual_off | оператор вручную выключил ИИ в диалоге | вручную |
pre_existing_dialog | переписка старше подключения бота (исторический чат) | вручную |
backlog_offline | сообщение пришло в момент переподключения | вручную |
ad_gated | режим «только реклама»: лид не с рекламы, диалог ведёт оператор | вручную |
default_chat_inactive | настройка «новые чаты с выключенным ИИ» (default_chat_active = false) | вручную |
guards_violation | сработала защита (спам / лимит / баланс) | вручную |
max_messages_reached | исчерпан лимит сообщений в диалоге | вручную |
conversation_cleared | история диалога очищена оператором | вручную |
connect_warmup | прогрев номера ~15 мин после подключения канала (защита от блокировки) | сама через ~15 мин |
undecrypted_placeholder | первое сообщение лида не удалось расшифровать | сама на следующем читаемом сообщении |
subscription_expired | подписка неактивна: ответ клиенту не отправлен, само сообщение сохранено в диалоге | сама после продления, на следующем сообщении клиента |
insufficient_balance | баланс исчерпан: ответ не отправлен, сообщение сохранено | сама после пополнения, на следующем сообщении клиента |
project_paused | проект поставлен на паузу: бот не отвечает, входящие сохраняются | сама после снятия с паузы, на следующем сообщении клиента |
ℹ️pipeline_stage_done(«диалог дошёл до финальной стадии воронки»), больше не используется (2026-07-21). Бот раньше сам замолкал после воронки, теперь этого нет. Причина может встречаться только в старых, ранее закрытых диалогах.
🔁 Авто-возобновление диалога (настройка проекта, по умолчанию выключена). Если включить, бот сам снимает паузу по таймеру и пишет клиенту приветствие. Но он трогает только «мягкие» паузы:guards_violation,backlog_offline,max_messages_reached,conversation_clearedи паузы без причины. Никогда не перебивает операторские паузы (operator_*), стоп клиента (client_stop), передачу специалисту (lead_handoff), классификацию (pre_existing_dialog,ad_gated,default_chat_inactive), прогрев/расшифровку и биллинг-паузы (subscription_expired,insufficient_balance,project_paused, те снимаются сами после оплаты/снятия с паузы), если человек или правило намеренно убрали бота из чата, авто-возобновление его туда не вернёт.
Состояния канала (WhatsApp)
| Состояние | Тип | Значение |
|---|---|---|
active | - | в эфире |
idle / init | мягкое | спит / поднимается, пройдёт само |
qridle | жёсткое | сессия слетела → пере-скан QR |
blocked | жёсткое | бан WhatsApp |
disabled | жёсткое | канал отключён |
no_channel | - | канал не привязан |
→ Канал отвалился / WhatsApp забанили
Ошибки API
Единый формат ответа: { "error": "текст", "code": "КОД" }.
| HTTP | code | Когда |
|---|---|---|
| 400 | INVALID_INPUT / INVALID_UUID | неверные/неполные данные |
| 401 | UNAUTHORIZED | нет/невалидны учётные данные |
| 403 | FORBIDDEN | нет прав (роль) |
| 404 | NOT_FOUND | объект не найден |
| 409 | CONFLICT | конфликт (напр. параллельное изменение) |
| 429 | RATE_LIMITED | превышен лимит (см. Retry-After) |
| 500 | SYSTEM_ERROR | внутренняя ошибка |
Ошибки функций
Когда функция падает, она возвращает модели { error, error_code }, и бот реагирует:
Пример error_code | Значение |
|---|---|
missing_params | не хватает обязательного параметра |
invalid_params | значение вне допустимого |
sub_merchant_not_connected | приём оплаты не настроен |
kaspi_auth_lost | потеряна авторизация Kaspi |
apipay_4xx / apipay_5xx | ошибка платёжного сервиса |
→ Функция не вызывается / падает
Простыми словами
Это «расшифровщик»: справочник всех технических кодов, которые могут попасться. Бот молчит и где-то мелькнул TRIAL_EXPIRED? Значит, кончился пробный период. Видишь у канала qridle? Слетела сессия, надо пере-сканировать QR. Прилетел от API FORBIDDEN? Не хватает прав по роли. Тут не нужно ничего настраивать, просто находишь свой код и понимаешь, что он значит и куда дальше смотреть.
Дальше: → Стадии, статусы, типы
Связано: Бот не отвечает · Канал отвалился · Формат данных