Коды ошибок
Каждая ошибка в боте, кабинете и воркере получает код вида E5103-1a2b3c4d:
5103— номер класса проблемы из таблиц ниже: по нему сразу видно, что за ошибка, ещё до чтения трейса;1a2b3c4d— отпечаток конкретного бага (стабилен между повторениями): по нему находится точный трейс на дашборде телеметрии.
Юзер видит код в сообщении «Что-то пошло не так», владелец — в JSON-ответах API (error_id) и на дашборде приёма ошибок. Повторения одного бага дают один и тот же код целиком.
Как этим пользоваться
Юзер прислал код → первая половина говорит, куда смотреть (касса? панель? БД?), вторая находит трейс на дашборде. Коды из «штатных» строк (например E3003 — не хватило баланса) в телеметрию не шлются — юзер просто видит понятное сообщение.
Система (1xxx)
| Код | Ошибка | Что случилось | Что делать |
|---|---|---|---|
E1001 | Ошибка конфигурации | Конфигурация неверна или небезопасна и отклонена при старте (плейсхолдер вместо секрета, неверный формат ключа и т.п.). | Проверьте .env по .env.example: длины ключей, отсутствие change_me, раздельные CRYPT/JWT ключи. |
E1101 | Ошибка валидации данных | Входные данные не прошли схему (pydantic) там, где это не было перехвачено. | Код места сбоя в трейсе; чаще всего это неожиданный ответ внешнего API. |
E1201 | Ошибка базы данных | PostgreSQL недоступен, соединение оборвано или запрос нарушил ограничение схемы. | Проверьте контейнер postgres, место на диске и миграции (alembic upgrade head). |
E1301 | Ошибка Redis | Redis недоступен или соединение оборвано (кэш, локи, очередь задач). | Проверьте контейнер redis; воркер и шедулер зависят от него. |
E1401 | Сетевая ошибка исходящего запроса | HTTP-запрос к внешнему сервису (касса, панель, Telegram) не прошёл: DNS, соединение, TLS. | Проверьте сеть/файрвол сервера и доступность адресата; единичные случаи не страшны — критичные пути ретраятся. |
E1402 | Таймаут | Операция не уложилась в отведённое время (внешний API или внутренняя задача). | Если массово — смотрите нагрузку сервера и время ответа внешнего сервиса. |
Доступ и данные (2xxx)
| Код | Ошибка | Что случилось | Что делать |
|---|---|---|---|
E2001 | Доступ запрещён | Действие потребовало роль/право, которых у актора нет. | Если это админ-операция — проверьте роль пользователя в кабинете. |
E2002 | Не найдено | Запрошенная сущность не существует (тариф, транзакция, юзер, промокод). | Обычно устаревшая кнопка/ссылка; если массово после обновления — issue. |
Подписки и покупки (3xxx)
| Код | Ошибка | Что случилось | Что делать |
|---|---|---|---|
E3001 | Ошибка покупки | Покупку невозможно завершить: недоступный тариф, конфликт состояния подписки. | Проверьте, что тариф активен и панель доступна; смотрите контекст на дашборде. |
E3002 | Триал недоступен | Юзер не проходит условия пробного периода (уже брал, есть подписка). | Штатная ситуация; код в телеметрию не шлётся, юзер видит объяснение. |
E3003 | Недостаточно средств | Баланса не хватает на операцию, оплачиваемую с кошелька. | Штатная ситуация; юзеру предлагается пополнение. |
Платежи (4xxx)
| Код | Ошибка | Что случилось | Что делать |
|---|---|---|---|
E4001 | Ошибка платежа | Платёжная операция не выполнена: касса вернула ошибку или неожиданный ответ. | Проверьте ключи кассы и её статус-страницу; смотрите message в трейсе. |
E4002 | Касса не настроена | Запрошен платёжный провайдер без активной конфигурации в БД. | Включите провайдера в кабинете (Платежи) или проверьте seed-роу. |
E4003 | Вебхук не прошёл проверку | Подпись/секрет/IP входящего платёжного вебхука не сошлись (ответ 403). | Единичные — фон интернета; массовые с одной кассы — проверьте секреты в кабинете и настройки уведомлений у кассы. |
E4004 | Недопустимый переход статуса | Попытка сменить статус транзакции, невозможная из текущего состояния (обычно дубль или сильно опоздавший вебхук). | Безопасно: идемпотентность отработала. Массово — смотрите, не шлёт ли касса дубли. |
Панель Remnawave (5xxx)
| Код | Ошибка | Что случилось | Что делать |
|---|---|---|---|
E5001 | Ошибка панели Remnawave | Панель вернула ошибку, не подпадающую под более точные коды 5xxx. | Смотрите message: чаще всего это неожиданный ответ API панели. |
E5002 | Панель отклонила авторизацию | Токен панели неверен или отозван; запрос не ретраится. | Обновите REMNAWAVE__TOKEN в .env или ключ в кабинете панели. |
E5003 | Панель временно недоступна | Таймаут/5xx/обрыв соединения с панелью; операция ретраится с бэкоффом, при длительном простое watchdog включит техрежим. | Проверьте панель и сеть до неё; после восстановления очередь дошлёт изменения. |
E5004 | Версия панели не поддерживается | Панель старше минимально поддерживаемой (2.8.0). | Обновите Remnawave. |
Telegram Bot API (6xxx)
| Код | Ошибка | Что случилось | Что делать |
|---|---|---|---|
E6001 | Ошибка Telegram Bot API | Прочие ошибки Bot API (сетевые сбои Telegram, недоступность серверов). | Единичные — норма; массовые — проверьте состояние Telegram и сеть сервера. |
E6002 | Флуд-лимит Telegram | Telegram попросил замедлиться (429): слишком много сообщений в секунду. | Рассылки уже дозируются; если код массовый — снизьте скорость рассылки. |
E6003 | Бот заблокирован юзером | Сообщение не доставлено: юзер заблокировал бота или удалил чат. | Штатно для рассылок; такие юзеры попадают в статистику ошибок доставки. |
E6004 | Некорректный запрос к Telegram | Bot API отверг запрос: битая разметка, слишком длинный текст, несуществующий message_id. | Смотрите message в трейсе — обычно это конкретное поле конкретного экрана. |
Неклассифицированное (9xxx)
| Код | Ошибка | Что случилось | Что делать |
|---|---|---|---|
E9001 | Неизвестная ошибка | Необработанное исключение, не подпадающее ни под один известный класс. | Смотрите трейс на дашборде телеметрии по полному коду ошибки; если повторяется — заведите issue с этим кодом. |