Коды ошибок аутентификации (mpbx-auth)

Возвращаются ядром аутентификации (W1-AUTH-01) и движком RBAC (W1-AUTH-02). Типы переводятся в HTTP-статусы, как для общих кодов: unauthenticated — 401, permission_denied — 403, invalid_argument — 400, not_found — 404, conflict — 409, unavailable — 503, config и internal — 500. Сообщения никогда не содержат пароль, токен, хеш, ключ или адрес электронной почты. Руководство: аутентификация.

Код	Тип	Значение	Что делать
MPBX-AUTH-INVALID-CREDENTIALS	unauthenticated	Вход не выполнен. Этот же код относится к неизвестному адресу электронной почты, неверному паролю, учётной записи, заблокированной после многих неудачных попыток, отключённому пользователю и приостановленной компании, поэтому ответ не раскрывает, какие учётные записи существуют. Также возвращается при смене пароля, если текущий пароль неверен.	Проверьте адрес электронной почты и пароль. После auth.lockout.max_failures неудачных попыток для этой учётной записи на auth.lockout.lockout_secs блокируется сеть (время удваивается при каждой последующей блокировке подряд; W4-AUTH-01: блокировка действует на клиентскую сеть, с которой пришли неудачные попытки, — адрес IPv4 или IPv6 /64, поэтому владелец по-прежнему может войти с другого места). Подождите, используйте другую сеть или попросите администратора снять блокировку (POST /api/v1/users/{id}/unlock или mpbx user unlock <company> <e-mail> на сервере). Вместо кода TOTP принимается код восстановления (recovery_code); неверный или уже использованный код отвечает MPBX-AUTH-TOTP-INVALID.
MPBX-AUTH-TOKEN-INVALID	unauthenticated	Токен доступа отсутствует, искажён, не EdDSA, подписан неизвестным или выведенным из обращения ключом (например, токеном другой установки или токеном старше периода перехода после ротации ключа), имеет неверную подпись либо неверного издателя или аудиторию.	Войдите снова. Службы, которые проверяют токены, должны загружать текущий набор JWK установки.
MPBX-AUTH-TOKEN-EXPIRED	unauthenticated	Срок действия токена доступа истёк (или он ещё не действителен).	Используйте токен обновления, чтобы получить новый токен доступа. Если это происходит сразу после входа, проверьте часы (auth.clock_leeway_secs).
MPBX-AUTH-TOKEN-REVOKED	unauthenticated	Токен доступа или его сессия отозваны (выход, смена пароля, повторное использование токена обновления, действие администратора).	Войдите снова.
MPBX-AUTH-REFRESH-INVALID	unauthenticated	Токен обновления искажён, неизвестен, просрочен (не использовался дольше auth.refresh_idle_ttl_secs или сессия старше auth.session_max_age_secs), его сессия завершена либо пользователь или компания отключены.	Войдите снова.
MPBX-AUTH-REFRESH-REUSED	unauthenticated	Токен обновления, который уже был обменян, предъявлен повторно — после окна допуска (auth.refresh_reuse_grace_secs, 20 с) или когда он старше непосредственно предыдущего токена. Это значит, что одна и та же сессия есть у двух сторон (украденный токен или клиент, отправивший одно обновление дважды), поэтому вся сессия отозвана, а её токены доступа помещены в список запрещённых. Внутри окна допуска предыдущий токен возвращает уже выданную пару.	Войдите снова. Клиенты должны выполнять обновления последовательно (одно в полёте на сессию) и всегда сохранять самый новый токен обновления. Если ошибка повторяется, проверьте устройство.
MPBX-AUTH-PASSWORD-POLICY	invalid_argument	Новый пароль нарушает политику паролей. Сообщение перечисляет нарушенные правила по ключам: too_short, too_long, too_few_character_classes, invalid_characters, common, contains_user_info, repetitive.	Выберите другой пароль; проще всего использовать фразу из нескольких слов.
MPBX-AUTH-KEY-INVALID	config	Ключевой материал JWT отсутствует или неверен: MPBX_JWT_SIGNING_KEY, MPBX_JWT_PUBLIC_KEY или MPBX_JWT_KID не заданы или некорректны, открытый ключ не принадлежит ключу подписи, ключ слабый или запись MPBX_JWT_PREVIOUS_KEYS некорректна. Сообщение называет переменную, но никогда не её значение.	Восстановите секреты установки из резервной копии или создайте их командой mpbx init на новой установке.
MPBX-AUTH-CONFIG-INVALID	config	Значение в разделе конфигурации [auth] вне допустимого диапазона (сообщение называет его и допустимый диапазон).	Исправьте mpbx.toml или переменную окружения MPBX__AUTH__*.
MPBX-AUTH-HASH	internal	Хеширование пароля или генератор случайных чисел операционной системы завершились ошибкой.	Проверьте хост (память для argon2, источник энтропии) и сообщите об ошибке вместе со строкой журнала.
MPBX-AUTH-REVOCATION-UNAVAILABLE	unavailable	Valkey не удалось прочитать для проверки списка запрещённых токенов. Запросы завершаются отказом, а не принимают возможно отозванный токен. Можно повторить.	Проверьте работоспособность Valkey.
MPBX-AUTH-PRINCIPAL-INACTIVE	unauthenticated	Токен доступа или ключ API действительны, но его пользователь отключён или удалён либо компания приостановлена. Проверяется при каждом запросе, поэтому отключение пользователя сразу прекращает его доступ.	Попросите администратора включить учётную запись или компанию снова.
MPBX-APIKEY-INVALID	unauthenticated	Ключ API неизвестен в указанной в нём компании, отозван, истёк или его секрет неверен. Один код для всех случаев, чтобы проверка не давала никаких сведений. Ключ, в части компании которого внесены изменения, также отклоняется здесь: ключ ищется только внутри компании, названной в строке.	Создайте новый ключ (Администрирование, Ключи API) и замените старый везде.
MPBX-KIOSK-INVALID	unauthenticated	Токен киоска табло (X-Kiosk-Token) отсутствует, неизвестен, отозван или истёк. Один код для всех случаев. Отзыв действует с следующего запроса.	Создайте новую ссылку киоска (Администрирование, Маршрутизация очередей, Киоски табло).
MPBX-RBAC-FORBIDDEN	permission_denied	Вызывающий не имеет разрешения, которое нужно операции (область, названная в документе OpenAPI), либо имеет его только для других отделов, чем отдел ресурса. Сообщение называет разрешение.	Попросите администратора назначить роль, которая его предоставляет; GET /api/v1/me показывает, что вы имеете и где.
MPBX-RBAC-ESCALATION	permission_denied	Назначение роли, создание пользовательской роли или выбор областей ключа API выдали бы разрешение, которым вызывающий не обладает для этой области (компания или отдел). Никто не может выдать больше, чем имеет сам.	Попросите того, кто имеет это разрешение там (обычно Владельца), сделать это.
MPBX-RBAC-UNKNOWN-PERMISSION	invalid_argument	Ключа разрешения нет в каталоге либо это системное разрешение, использованное в роли компании или ключе API.	Используйте ключи, перечисленные в руководстве по RBAC.
MPBX-RBAC-BUILTIN-READONLY	conflict	Встроенные роли (Пользователь, Администратор приёмной, Супервайзер, Администратор отдела, Менеджер, Владелец) нельзя переименовать, изменить или удалить.	Создайте пользовательскую роль с нужными разрешениями.
MPBX-RBAC-LAST-OWNER	conflict	Изменение оставило бы компанию без Владельца на уровне всей компании или установку без Владельца системы.	Сначала передайте роль другому пользователю.
MPBX-RBAC-NOT-FOUND	not_found	Роли, назначения ролей или отдела нет в этой компании (идентификаторы другой компании ведут себя как отсутствующие).	Проверьте идентификатор; список ролей компании доступен через API ролей.
MPBX-RBAC-SYSTEM-ROLE-REQUIRED	permission_denied	Токен уровня системы (или запрос его получить) для пользователя, который не имеет роли Администратора системы или Владельца системы, например после отзыва роли.	Войдите снова с токеном компании или попросите Владельца системы выдать роль.
MPBX-ACCOUNT-SYSTEM	permission_denied	Субъект, который не имеет более высокого ранга, чем учётная запись с системной ролью (Владелец системы или Администратор системы), попытался изменить её: поля, статус, удаление, пароль, 2FA, блокировку, назначение ролей, системные роли, внутренний номер или ключи API. Владелец системы > Администратор системы > нет роли; другого Владельца системы меняет только Владелец системы; субъект компании или ключ API не имеет системного ранга (W1-SEC-01-M1, rbac.md).	Обратитесь к Владельцу системы.
MPBX-AUTH-TOTP-REQUIRED	unauthenticated	Адрес электронной почты и пароль верны, но для учётной записи включена двухфакторная аутентификация TOTP, а вход не содержал totp_code.	Попросите пользователя ввести 6-значный код из приложения-аутентификатора и повторите вход с тем же адресом и паролем плюс totp_code.
MPBX-AUTH-TOTP-INVALID	unauthenticated	totp_code (или recovery_code) неверен, относится к другому временному окну (допускается отклонение на один шаг в 30 секунд), уже был использован однократно либо второй фактор учётной записи заблокирован после auth.lockout.max_failures неверных кодов в окне с любой сети (замечание к PR #109: бюджет на всю учётную запись; тогда код не проверяется и код восстановления не расходуется). Считается неудачным входом для блокировки сети, как и неверный пароль.	Введите текущий код; проверьте часы телефона. После повторных неверных кодов подождите auth.lockout.lockout_secs (время удваивается при каждой блокировке подряд) или попросите администратора снять блокировки входа.
MPBX-AUTH-TOTP-CODE-MISMATCH	invalid_argument	POST /api/v1/auth/totp/verify: код не совпадает с ожидающим секретом. TOTP остаётся выключенным, пока код не совпадёт. Также ответ на первый код при регистрации входа и на выключение TOTP, когда код неверен или второй фактор учётной записи заблокирован (тот же бюджет на всю учётную запись, что и у MPBX-AUTH-TOTP-INVALID).	Повторно отсканируйте секрет из POST /api/v1/auth/totp/enroll и отправьте текущий код.
MPBX-AUTH-TOTP-ALREADY-ENABLED	conflict	Запрошена регистрация, хотя TOTP уже включён для учётной записи. Действующий второй фактор никогда не заменяется молча.	Администратор сначала сбрасывает фактор (управление пользователями), затем регистрация выполняется снова.
MPBX-AUTH-TOTP-NOT-ENROLLED	conflict	POST /api/v1/auth/totp/verify без ожидающей регистрации (никогда не регистрировалась или уже подтверждена), либо регистрация для учётной записи без локального пароля.	Сначала вызовите POST /api/v1/auth/totp/enroll.
MPBX-AUTH-TOTP-UNAVAILABLE	unavailable	На сервере нет хранилища секретов (MPBX_MASTER_KEY не загружен), поэтому секреты TOTP нельзя ни зашифровать, ни открыть. Вход в учётную запись с включённым TOTP завершается отказом с этим кодом.	Запустите сервер с секретами установки из mpbx init.
MPBX-AUTH-BUSY	unavailable	Все слоты хеширования паролей были заняты 2 секунды, поэтому пароль не проверялся (HTTP 503 с Retry-After). Argon2 расходует около 19 МиБ и один процессор на проверку, поэтому сервер выполняет не более двух проверок на процессор одновременно; это ограничение на работу хеширования без аутентификации во время наплыва входов. Ничего в учётной записи не проверялось и не менялось; сбой не учитывается в блокировке. Можно повторить.	Повторите попытку через некоторое время. Если это происходит без наплыва запросов, посмотрите предупреждения MPBX-AUTH-BUSY в журнале и загрузку процессора хоста.
MPBX-AUTH-TOTP-ENROLMENT-REQUIRED	unauthenticated	Пароль верен, но политика двухфакторной аутентификации компании распространяется на учётную запись (/api/v1/two-factor-policy: на всех или на одну из её ролей), а аутентификатора у неё ещё нет. Сессия не открыта; ничего не регистрируется молча.	Объясните пользователю политику, вызовите POST /api/v1/auth/totp/enrolment с тем же адресом и паролем, чтобы получить секрет (QR-код), затем войдите с первым кодом (totp_code): это подтверждает аутентификатор и один раз возвращает коды восстановления.
MPBX-AUTH-TOTP-ENROLMENT-NOT-REQUIRED	conflict	POST /api/v1/auth/totp/enrolment для учётной записи, на которую политика не распространяется (она всё же может зарегистрироваться после входа).	Войдите, затем зарегистрируйтесь в разделе «Безопасность учётной записи».
MPBX-AUTH-TOTP-ENROLMENT-CODE-INVALID	unauthenticated	POST /api/v1/auth/totp/enrolment без одноразового кода, отправленного по почте командой POST /api/v1/auth/totp/enrolment/code, либо с кодом, который неверен, просрочен (10 минут), уже использован, заменён более новым, сожжён после 5 неверных попыток или отправлен на адрес, которого у учётной записи больше нет (FU-AUTH01-L3). Неверный код также учитывается в блокировке входа.	Запросите новый код (POST /api/v1/auth/totp/enrolment/code) и введите тот, что пришёл в самом новом письме.
MPBX-AUTH-TOTP-ENROLMENT-CODE-THROTTLED	conflict (HTTP 429)	POST /api/v1/auth/totp/enrolment/code вызван менее чем через минуту после последнего кода либо после 5 кодов для учётной записи (или её адреса) или 20 кодов из клиентской сети за час. Задано Retry-After.	Подождите, затем используйте самый новый код, уже находящийся в почтовом ящике.
MPBX-AUTH-TOTP-ENROLMENT-MAIL-UNAVAILABLE	unavailable	Код регистрации нельзя отправить по электронной почте: у компании нет провайдера электронной почты (а у установки нет [email.smtp]), либо провайдер отклонил письмо. Код аннулирован; ничего не зарегистрировано.	Настройте провайдера электронной почты (Настройки, Электронная почта) или администратор снимает политику двухфакторной аутентификации с учётной записи, пока её не настроят.
MPBX-AUTH-TOTP-POLICY	conflict	POST /api/v1/auth/totp/disable для учётной записи, на которую распространяется политика двухфакторной аутентификации компании.	Попросите администратора изменить политику или сбросить фактор (POST /api/v1/users/{id}/two-factor-reset).
MPBX-AUTH-REAUTH-FAILED	permission_denied	Чувствительное изменение собственной учётной записи требует текущий пароль (регистрация и удаление TOTP, новые коды восстановления, сброс собственного пароля через маршруты пользователя), и он был неверен либо вход из этой сети заблокирован. Учитывается в блокировке как неверный вход. HTTP 403, чтобы клиент не принял это за истёкшую сессию.	Введите текущий пароль.
MPBX-AUTH-INVITE-INVALID	unauthenticated	Ссылка-приглашение неизвестна, просрочена, уже использована, заменена более новым приглашением либо учётная запись отключена или уже имеет пароль. Один код для всех случаев, поэтому ответ ничего не раскрывает.	Попросите администратора отправить новое приглашение (POST /api/v1/users/{id}/invitation).
MPBX-AUTH-INVITE-ONBOARDED	conflict	Приглашение запрошено для учётной записи, которая уже имеет пароль.	Вместо этого используйте сброс пароля.
MPBX-AUTH-INVITE-HOST	conflict	POST /api/v1/users/{id}/invitation отправлено на веб-адрес, который не принадлежит компании (в режиме нескольких компаний — адрес другой компании или адрес установки для компании, которая не является компанией по умолчанию). Ссылка в письме строится из этого адреса, поэтому она не привела бы в компанию.	Отправьте приглашение с собственного веб-адреса компании (<company>.<pbx domain>). За прокси или под другим публичным именем отправляйте приглашение с публичного имени, которое открывают пользователи, и сохраняйте исходный Host (см. руководство по аутентификации, FU-AUTH01-L5).

Первоначальная настройка и повышение доступа (W4-WEB-06)

Возвращаются маршрутами настройки (/api/v1/setup/*) и POST /api/v1/auth/elevate. Руководство: мастер первоначальной настройки.

Код	Тип	Значение	Что делать
MPBX-SETUP-TOKEN-INVALID	unauthenticated	Токен в ссылке настройки неверен или неполон либо у этой установки нет токена настройки (MPBX_SETUP_TOKEN_SHA256 не задан или некорректен). Один код для всех случаев, поэтому проверка ничего не раскрывает. Отклонённые попытки ограничиваются по клиентской сети и записываются в журнал аудита установки (setup.refused).	Используйте самую новую ссылку, которую напечатал установщик. Выпустите новую командой mpbx-ctl setup-url (виртуальная машина) или удалив значения MPBX_SETUP_TOKEN_* и повторно выполнив mpbx init (Compose, Kubernetes); старая ссылка перестанет работать.
MPBX-SETUP-TOKEN-EXPIRED	unauthenticated	Токен верен, но истёк срок MPBX_SETUP_TOKEN_EXPIRES_AT (по умолчанию через 24 часа после mpbx init).	Выпустите новую ссылку, как описано выше.
MPBX-SETUP-COMPLETE	conflict	Первый Владелец системы уже существует: настройка завершена по ссылке (токен израсходован) или в базе данных уже есть Владелец системы (восстановление, заранее заполненная установка). Маршруты токена настройки никогда не создают другого владельца, какие бы секреты установки ни были сохранены. Также ответ на подписанные шаги настройки после завершения мастера.	Войдите как обычно. Чтобы добавить администраторов, Владелец системы выдаёт роли в консоли.
MPBX-SETUP-OWNER-PENDING	conflict	Владелец системы уже создан по ссылке и ожидает кода аутентификатора.	Завершите подтверждение (POST /api/v1/setup/owner/confirm), получите новый QR-код (POST /api/v1/setup/owner/totp) или начните заново (POST /api/v1/setup/owner/reset).
MPBX-SETUP-NO-OWNER-PENDING	conflict	Попытка подтвердить, перезапустить или сбросить владельца, когда никто не ожидает подтверждения.	Сначала создайте владельца (POST /api/v1/setup/owner).
MPBX-SETUP-CREDENTIALS-INVALID	unauthenticated	Адрес электронной почты или пароль не совпадают с Владельцем системы, созданным по ссылке. Неверный пароль учитывается в блокировке входа для этой учётной записи.	Введите адрес электронной почты и пароль, выбранные на первом шаге, или начните заново.
MPBX-AUTH-STEP-UP-UNAVAILABLE	conflict	POST /api/v1/auth/elevate: доступ уровня всей установки подтверждается кодом аутентификатора учётной записи, а у этой учётной записи нет подтверждённого аутентификатора.	Настройте двухфакторный вход в разделе «Безопасность учётной записи», затем повторите попытку.