        Обзор
      

Формат ошибок

Все ошибки возвращаются в едином JSON-формате. Поле error содержит машиночитаемое описание, поле details — опциональные подробности (не всегда присутствует).

Структура

json

{
  "status": "error",
  "error": "описание ошибки",
  "code": 400,
  "details": ...  // опционально
}

Успешный ответ для сравнения

json

{
  "status": "success",
  "data": {
    "ok": true,
    ...
  }
}

400 Bad Request

400 "code must be int"

Передан код авторизации не в виде числа.

где POST /auth/createToken

401 Unauthorized

401 "Unauthorized"

Заголовок авторизации передан, но токен/SecretKey/InitData не прошёл проверку — невалиден или не существует.

где Любой защищённый метод

401 "Token or InitData is required"

Запрос к защищённому методу пришёл без каких-либо заголовков авторизации.

где Любой защищённый метод

401 "invalid code"

Переданный одноразовый код не найден в базе — либо неверный, либо уже использован.

где POST /auth/createToken

403 Forbidden

403 "access denied"

Пользователь авторизован, но его роль не входит в список разрешённых (admin_roles в конфиге). Актуально при авторизации через Telegram InitData.

где Любой защищённый метод

404 Not Found

404 "user not found"

Пользователь авторизован, но его запись не найдена в таблице users. Такое возможно если пользователь был удалён вручную из БД.

где GET /api/user/get

409 Conflict

409 "session already exists"

Токен для этого пользователя уже существует. Повторный вызов createToken без инвалидации предыдущего токена вернёт эту ошибку.

где POST /auth/createToken

409 "active code already exists"

Для этого пользователя уже есть активный одноразовый код, который ещё не истёк. Нужно дождаться истечения 5 минут или использовать текущий.

где POST /auth/createCode

409 "report with this type already exists for today"

Отчёт с таким типом смены (day / night) за сегодня уже создан. За один день можно создать один дневной и один ночной отчёт.

где POST /api/report/create

410 Gone

410 "code expired"

Одноразовый код найден в базе, но время его жизни (5 минут) истекло. Нужно запросить новый код через бота.

где POST /auth/createToken

422 Unprocessable Entity

422 "missing required fields"

В теле запроса отсутствуют обязательные поля. Поле details содержит список недостающих параметров.

где Любой POST метод

пример ответа

{
  "status": "error",
  "error": "missing required fields",
  "code": 422,
  "details": [
    { "param": "money" },
    { "param": "checks" }
  ]
}

422 "invalid type"

Значение параметра не соответствует ожидаемому типу или набору допустимых значений (literal). details.available показывает что ожидалось.

где POST /api/report/create POST /api/credit/create

пример ответа

{
  "status": "error",
  "error": "invalid type",
  "code": 422,
  "details": {
    "param": "report_type",
    "available": "'day' or 'night'"
  }
}

422 "invalid query params"

Неверный тип или формат query-параметров GET-запроса.

где Любой GET метод

429 Too Many Requests

429 "too many requests"

Превышен лимит запросов с одного IP-адреса. Лимиты: 5 req/min для /auth/createToken, 20 req/min для всех остальных. Счётчик сбрасывается через 60 секунд.

где Любой метод

500 Internal Server Error

500 "internal server error"

Необработанное исключение на стороне сервера. Детали записываются в лог. Если ошибка воспроизводима — проверьте логи PM2 командой pm2 logs bk-reports-backend.

где Любой метод