Документация › Справочники › Коды ошибок
Коды ошибок и состояния
Справочник кодов и состояний, которые встречаются в системе: почему бот не отвечает, какие ошибки отдаёт API, что значат состояния канала. Диагностика по шагам: в Бот не отвечает.
⏱ 7 мин · 👤 справочник · 🟢 live
Доступ к ответу бота (eligibility)
Почему бот может не отвечать (проверка перед ответом):
| Код | HTTP | Значение |
|---|---|---|
PROJECT_NOT_ACTIVE | 403 | проект в черновике |
ACCOUNT_BANNED | 403 | аккаунт заблокирован |
INSUFFICIENT_BALANCE | 402 | пустой баланс |
NO_SUBSCRIPTION | 402 | нет подписки |
SUBSCRIPTION_EXPIRED | 402 | подписка истекла |
WHATSAPP_TRIAL_EXPIRED | 402 | бесплатный период WhatsApp кончился (14 дней с подключения номера, 30 с промокодом партнёра) |
SUBSCRIPTION_NO_EXPIRY | 402 | подписка есть, но у неё нет даты окончания (расходится журнал, чинится на нашей стороне) |
TRIAL_EXPIRED_PAYMENT_REQUIRED | 402 | попытка подключить или переподключить номер после бесплатного периода без подписки |
CHANNEL_BANNED | 409 | WhatsApp ограничил этот номер: ссылка для подключения его не поднимает, а отправить с него из Диалогов нельзя; нужен другой номер (кнопка «Подключить другой номер» в Каналах) |
PREVIOUS_NUMBER | 409 | номер проекта сменили, а этот человек писал на прежний и новый не знает; первым писать ему с нового номера нельзя, отправка откроется, когда он напишет сам |
PREVIOUS_NUMBER_CHECK_FAILED | 503 | не удалось проверить, писал ли человек на прежний номер; попробуйте через минуту |
GATEWAY_UNAVAILABLE | 503 | Не удалось отвязать ограниченный номер на сервере WhatsApp; попробуйте через минуту, новый номер подключается только после отвязки старого |
PROJECT_NOT_FOUND | 404 | проект не найден |
AUTH_TEMPORARILY_UNAVAILABLE | 503 | вход на месте, но сервер проверки сессии не ответил вовремя; повторите запрос через пару секунд, выходить и входить заново не нужно |
→ Бот не отвечает, диагностика
Причины автопаузы ИИ (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 | бот дошёл до потолка своих ответов в этом диалоге (настройка «Макс. ответов бота на диалог», по умолчанию 200) и передал диалог вам: клиенту написано, что подключится менеджер, на диалоге стоит метка «ответьте руками», вам ушло уведомление dialog_too_long | вручную: ответьте сами или включите бота в шапке диалога |
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)
| Статус в кабинете | Тип | Значение |
|---|---|---|
| Подключён (номер) | - | в эфире |
| Поднимаем подключение... / QR на экране | - | ждём скан, QR живёт около минуты |
| Переподключаемся... | мягкое | короткий обрыв, восстановится само |
| Сессия разлогинена, привяжите заново | жёсткое | устройство отвязано → новый QR |
| Номер заблокирован WhatsApp, отправки остановлены | жёсткое | бан номера |
| Ошибка подключения | обычно мягкое | сбой на шлюзе, повтори подключение |
| Не подключён | - | канал не привязан |
→ Канал отвалился / 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 | INTERNAL_ERROR | необработанная ошибка (полный текст в логах и Sentry, наружу только общий) |
| 500 | DATABASE_ERROR | сбой запроса к базе |
| 402 | INSUFFICIENT_BALANCE | «Составить за меня»: на балансе проекта меньше $0.30 |
| 502 | COMPOSE_FAILED / PREFILL_FAILED | «Составить за меня»: ИИ не собрал описание или не разобрал текущее; деньги не списаны, попробуй ещё раз |
| 500 | SAVE_FAILED | «Составить за меня»: описание собрано, но не сохранилось; повтори |
| 400 | KASPI_CLIENT_NOT_FOUND | оплата через Kaspi: на указанном номере нет приложения Kaspi, счёт не выставлен; укажите номер, где Kaspi установлен |
| 503 | PROVIDER_UNAVAILABLE | оплата через Kaspi сейчас недоступна; попробуйте через несколько минут или оплатите картой |
Ошибки функций
Когда функция падает, она возвращает модели { error, error_code }, и бот реагирует:
Пример error_code | Значение |
|---|---|
missing_params | не хватает обязательного параметра |
invalid_params | значение вне допустимого |
sub_merchant_not_connected | приём оплаты не настроен |
kaspi_auth_lost | потеряна авторизация Kaspi |
payment_service_4xx / payment_service_5xx / payment_service_network | ошибка платёжного сервиса |
→ Функция не вызывается / падает
Простыми словами
Это «расшифровщик»: справочник всех технических кодов, которые могут попасться. Бот молчит и где-то мелькнул WHATSAPP_TRIAL_EXPIRED? Значит, кончился бесплатный период. Видишь у канала «Сессия разлогинена»? Устройство отвязано, надо отсканировать QR заново. Прилетел от API FORBIDDEN? Не хватает прав по роли. Тут не нужно ничего настраивать, просто находишь свой код и понимаешь, что он значит и куда дальше смотреть.
Дальше: → Стадии, статусы, типы
Связано: Бот не отвечает · Канал отвалился · Формат данных