NeuronChat

Справочник ошибок

Когда в кабинете, виджете или ответе API появляется ошибка, в теле ответа часто есть поля code и doc — ссылка на этот раздел. Найдите код ниже: для каждого указаны типичная причина и конкретные шаги, что исправить без обращения в поддержку.

Быстрые ссылки по коду

Вход и аккаунт

Авторизация, подтверждение почты и регистрация.

auth_required

HTTP 401 · Нужна авторизация

Чтобы продолжить, войдите в аккаунт.

Почему так

  • Запрос выполнен без действующей сессии или с истёкшим входом.
  • Часть API доступна только владельцу клиента (кабинет).

Что сделать

  1. Откройте страницу входа и авторизуйтесь под своим email.
  2. Если вы уже вошли — обновите страницу или выйдите и войдите снова.

email_not_verified

HTTP 403 · Email не подтверждён

Вход возможен только после подтверждения почты кодом из письма.

Почему так

  • Регистрация начата, но код из письма ещё не введён.

Что сделать

  1. Завершите регистрацию на странице «Регистрация» и введите код в течение 15 минут.
  2. Если письма нет — проверьте «Спам» или запросите код повторно.

email_already_registered

HTTP 400 · Email уже зарегистрирован

Аккаунт с таким email уже есть.

Почему так

  • Один email можно привязать только к одному аккаунту.

Что сделать

  1. Войдите через страницу входа.
  2. Для нового аккаунта укажите другой email.

registration_otp_invalid

HTTP 400 · Неверный код

Код из письма не подошёл.

Почему так

  • Опечатка в цифрах, введён старый код или превышено число попыток.

Что сделать

  1. Проверьте 6 цифр из последнего письма без пробелов.
  2. Нажмите «Отправить код снова» и введите код из нового письма.

registration_otp_expired

HTTP 400 · Код устарел

Код из письма больше не действует — с момента отправки прошло больше 15 минут.

Почему так

  • Код подтверждения ограничен по времени в целях безопасности.

Что сделать

  1. Нажмите «Отправить код снова» и введите цифры из нового письма.

registration_resend_cooldown

HTTP 429 · Слишком частая отправка

Письмо с кодом можно отправить повторно не раньше чем через минуту.

Почему так

  • Между письмами выдерживается пауза, чтобы защитить почту от спама.

Что сделать

  1. Подождите немного, проверьте папку «Спам» и нажмите «Отправить код снова».

Виджет и агент

Готовность виджета, подписка, промпт и база знаний.

client_not_found

HTTP 404 · Клиент или виджет не найден

Указанный клиент не существует или был удалён.

Почему так

  • В запросе передан неверный идентификатор клиента (виджета).
  • В кабинете обращение идёт к чужому или устаревшему clientId.

Что сделать

  1. В разделе «Виджет» скопируйте актуальный код установки с правильным clientId.
  2. Проверьте, что виджет вставлен с того же проекта, что и ваш аккаунт.

subscription_required

HTTP 403 · Нужна подписка для виджета

На бесплатном тарифе без триала виджет недоступен.

Почему так

  • Тариф FREE без активного триала не включает публичный виджет.

Что сделать

  1. Оформите подписку или активируйте триал в разделе «Тарифы».

bot_disabled

HTTP 403 · Агент выключен (чат на сайте)

Посетитель написал в виджет, но агент отключён в настройках.

Почему так

  • Флаг активности агента (isActive) выключен — публичный чат не обрабатывает сообщения.

Что сделать

  1. Кабинет → Виджет или Настройки агента → включите агента и сохраните.
  2. Проверьте виджет на сайте после публикации настроек.

widget_disabled

HTTP 403 · Агент выключен (диагностика в кабинете)

Проверка виджета в кабинете: агент неактивен.

Почему так

  • Диагностика «Проверить виджет» обнаружила, что флаг активности агента выключен.
  • Это тот же переключатель, что и для кода bot_disabled в чате, но контекст — отчёт в кабинете, а не ответ посетителю.

Что сделать

  1. Кабинет → Виджет → включите агента и снова запустите проверку.

prompt_invalid

HTTP 400 · Системный промпт не задан

Промпт слишком короткий или содержит недопустимые символы.

Почему так

  • Для ответов агенту нужен осмысленный системный промпт.

Что сделать

  1. Настройки агента → основные настройки — заполните системный промпт (от 10 символов) и сохраните.

no_knowledge

HTTP 400 · Нет базы знаний

Не загружены документы, FAQ и обход сайта.

Почему так

  • Агенту нечем опираться при ответах.

Что сделать

  1. Раздел «База знаний»: загрузите документы, FAQ, запустите обход сайта или заполните бриф.

telegram_same_bot_notifications

HTTP 400 · Один и тот же бот для чата и уведомлений

Токен бота уведомлений совпадает с ботом-агентом.

Почему так

  • Технически один бот не может одновременно быть «агентом в диалоге» и «ботом только для заявок».

Что сделать

  1. Создайте второго бота в @BotFather для уведомлений о заявках.
  2. Укажите его токен на странице уведомлений; агентский токен оставьте в интеграции мессенджеров.

Лимиты и нагрузка

Тарифные лимиты и защита от частых запросов.

LIMIT_REACHED

HTTP 429 · Лимит диалогов по тарифу

Исчерпан месячный лимит диалогов на текущем тарифе.

Почему так

  • Каждый новый разговор (новая сессия чата) увеличивает счётчик.
  • Лимит задаётся тарифом; при триале может действовать лимит как у тарифа «Бизнес».

Что сделать

  1. Откройте «Тарифы» и повысьте план или дождитесь сброса счётчика (раз в ~30 дней от даты сброса).
  2. После оплаты лимиты обновляются без ожидания конца календарного месяца.

RATE_LIMIT

HTTP 429 · Слишком много запросов

С вашей стороны слишком частые сообщения в чат.

Почему так

  • Защита от злоупотреблений: за короткий интервал допускается ограниченное число запросов.

Что сделать

  1. Подождите около минуты и отправьте сообщение снова.
  2. Не используйте скрипты или автоотправку в тот же чат.

Безопасность сообщений

Модерация, prompt injection и SQL-подобные конструкции.

BLOCKED_CONTENT

HTTP 429 · Сообщение отклонено модерацией

Текст не проходит фильтр запрещённых тем платформы.

Почему так

  • Сработала политика контента: в сообщении есть темы или формулировки, которые платформа не пропускает.
  • Отличие от INJECTION: здесь блокируется тематика, а не попытка переопределить инструкции бота.

Что сделать

  1. Переформулируйте вопрос нейтрально, без запрещённых слов и сомнительных ссылок.
  2. При ложном срабатывании отправьте в поддержку точный текст сообщения и время запроса.

INJECTION

HTTP 429 · Подозрение на prompt injection

Такой запрос нельзя обработать — он похож на попытку изменить правила ассистента.

Почему так

  • В тексте обнаружены команды к модели: «забудь инструкции», «отвечай как…», служебные теги и похожие шаблоны.
  • В виджете на сайте такой запрос обычно не обрывается ошибкой — бот отвечает вежливым отказом (HTTP 200). Код INJECTION чаще виден в API и интеграциях.

Что сделать

  1. Задайте обычный вопрос о товаре, услуге или заказе — без указаний, как должен вести себя ассистент.
  2. Для тестов роли и стиля используйте настройки агента в кабинете, а не команды в чате посетителя.

SQL_INJECTION

HTTP 429 · Сообщение отклонено

Текст похож на SQL-инъекцию и не принимается.

Почему так

  • В сообщении есть конструкции, характерные для атак на базы данных.

Что сделать

  1. Уберите из текста SQL-подобные фрагменты и повторите вопрос обычным языком.

Телефон и сайт

Поля профиля и быстрый старт.

phone_required

HTTP 400 · Не указан телефон

Поле телефона обязательно для этого шага.

Почему так

  • Для завершения профиля или заявки требуется номер.

Что сделать

  1. Заполните телефон в форме и сохраните снова.

phone_invalid

HTTP 400 · Некорректный номер телефона

Номер не распознан как действительный.

Почему так

  • Неверный формат, опечатка или номер не из зоны +7.

Что сделать

  1. Укажите мобильный в формате +7… или 8… / 9… — как в подсказке формы.

phone_zone_ru_kz

HTTP 400 · Нужен номер России или Казахстана

Допускаются только номера зоны +7 (РФ и КЗ).

Почему так

  • Продукт ориентирован на эту зону нумерации.

Что сделать

  1. Введите номер с кодом +7 или выберите другой способ связи, если он доступен в форме.

phone_template_not_allowed

HTTP 400 · Тестовый или шаблонный номер

Такой номер нельзя использовать для регистрации.

Почему так

  • Обнаружен известный «заглушечный» или повторяющийся шаблон (например, одинаковые цифры).

Что сделать

  1. Укажите реальный контактный номер, на который можно связаться с вами.

phone_already_used

HTTP 400 · Номер уже занят

Этот номер уже указан у другого аккаунта.

Почему так

  • Один номер телефона может быть привязан только к одному клиенту.

Что сделать

  1. Укажите свой контактный номер или обратитесь в поддержку, если это ваш номер.

website_required

HTTP 400 · Не указан URL сайта

Введите адрес сайта компании.

Почему так

  • Поле URL пустое, а для шага требуется значение.

Что сделать

  1. Укажите полный адрес, например https://example.ru

website_invalid_url

HTTP 400 · Некорректный URL

Строка не является допустимой ссылкой.

Почему так

  • Опечатка, пробелы или недопустимые символы в адресе.

Что сделать

  1. Скопируйте адрес из браузера (с https://) и вставьте в поле.

website_protocol_invalid

HTTP 400 · Нужен http или https

Разрешены только протоколы http и https.

Почему так

  • Указан другой протокол (ftp, file и т.д.).

Что сделать

  1. Замените ссылку на https://…

website_placeholder

HTTP 400 · Тестовый или служебный домен

Нельзя использовать example.com, localhost и подобные адреса.

Почему так

  • Эти домены зарезервированы для документации и не являются сайтом компании.

Что сделать

  1. Укажите реальный домен вашего сайта в продакшене.

Промокоды и оплата

Активация скидок и подарочных подписок.

promo_not_found

HTTP 400 · Промокод не найден

Такого промокода нет — проверьте написание.

Почему так

  • Опечатка в коде или промокод ещё не создан в админке.

Что сделать

  1. Проверьте написание (регистр не важен).
  2. Уточните действующий код у поддержки.

promo_not_active

HTTP 400 · Промокод ещё не активен

Дата начала действия промокода ещё не наступила.

Почему так

  • В настройках промокода задана будущая дата «с».

Что сделать

  1. Подождите даты старта или используйте другой промокод.

promo_expired

HTTP 400 · Промокод истёк

Срок действия промокода уже прошёл.

Почему так

  • У промокода есть дата окончания.

Что сделать

  1. Запросите новый промокод у поддержки или оформите оплату без скидки.

promo_exhausted

HTTP 400 · Промокод исчерпан

Достигнут лимит использований.

Почему так

  • У промокода ограниченное число активаций.

Что сделать

  1. Используйте другой код или тариф без промокода.

promo_plan_mismatch

HTTP 400 · Промокод не для этого тарифа

Промокод привязан к другому тарифу.

Почему так

  • В настройках промокода указано ограничение по тарифу.

Что сделать

  1. Выберите тариф, для которого действует промокод, или оплатите без кода.

promo_subscription_only

HTTP 400 · Это промокод на подписку

Его нужно активировать отдельной кнопкой, а не при оплате.

Почему так

  • Тип промокода SUBSCRIPTION не совместим с созданием платежа.

Что сделать

  1. Используйте раздел с активацией подарочной подписки по промокоду.

Почта и доставка писем

SMTP и отправка кодов подтверждения.

mail_not_configured

HTTP 503 · Почта не настроена

Сейчас не получается отправить письмо с кодом — почтовый сервис временно недоступен.

Почему так

  • На сервере не заданы параметры SMTP (техническая настройка для администратора).

Что сделать

  1. Попробуйте через несколько минут. Если не помогает — напишите в поддержку.
  2. Администратору: задайте SMTP_HOST, SMTP_PORT, EMAIL_FROM и при необходимости SMTP_USER, SMTP_PASS.

mail_send_failed

HTTP 502 · Не удалось отправить письмо

Письмо с кодом не удалось доставить.

Почему так

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

Что сделать

  1. Подождите минуту и нажмите «Отправить код снова».
  2. Проверьте папку «Спам» и правильность email.

Системные ошибки

Сбои сервера и общая валидация форм.

server_error

HTTP 500 · Ошибка сервиса (проверка и фоновые задачи)

Сервер не смог завершить проверку или служебную операцию.

Почему так

  • Сбой при диагностике виджета, обходе сайта или другой фоновой задаче.

Что сделать

  1. Повторите проверку через несколько минут.
  2. Если ошибка повторяется — напишите в поддержку с временем и разделом кабинета.

internal_error

HTTP 500 · Ошибка обработки формы

Не удалось завершить действие — регистрация, сохранение настроек или другой шаг кабинета.

Почему так

  • На сервере произошло непредвиденное исключение при обработке вашего запроса.

Что сделать

  1. Обновите страницу и повторите действие.
  2. Если не помогает — обратитесь в поддержку и укажите, что делали перед ошибкой.

validation_failed

HTTP 400 · Данные формы не прошли проверку

Проверьте заполнение полей — одно из значений указано неверно.

Почему так

  • Одно или несколько полей не соответствуют формату или ограничениям.

Что сделать

  1. Прочитайте текст ошибки у поля или в уведомлении и исправьте значение.