Коды ошибок API (mpbx-api)
Эти коды возвращаются в поле code тел application/problem+json (см. docs/api/CONVENTIONS.md).
Общие коды видов (MPBX-NOT-FOUND, MPBX-INVALID-ARGUMENT, ...) описаны в common.md.
| Код | HTTP | Значение | Что делать |
|---|---|---|---|
MPBX-INVALID-QUERY | 400 | Параметр limit, sort или filter недопустим: неизвестное или не поддерживающее фильтрацию поле, неверный оператор, значение неверного типа, слишком много фильтров. errors[].field называет параметр. | Исправьте параметр; допустимые поля см. в документации конечной точки. |
MPBX-INVALID-CURSOR | 400 | cursor искажён или выдан для другого фильтра или сортировки. | Начните с первой страницы; никогда не редактируйте курсоры и не используйте их повторно для других запросов. |
MPBX-PRECONDITION-REQUIRED | 428 | В запросе PUT, PATCH или DELETE нет заголовка If-Match. | Выполните GET для ресурса и передайте его ETag в If-Match. |
MPBX-PRECONDITION-FAILED | 412 | If-Match не совпадает: ресурс изменился с момента вашего чтения. | Выполните GET снова, повторно примените изменение и повторите с новым ETag. |
MPBX-IDEMPOTENCY-KEY-INVALID | 400 | Idempotency-Key пуст, длиннее 255 символов, содержит не видимые ASCII-символы или передан более одного раза. | Передайте один ключ из 1–255 видимых ASCII-символов (подойдёт UUID). |
MPBX-IDEMPOTENCY-KEY-REUSED | 422 | Тот же вызывающий уже использовал этот ключ на этом маршруте с другим путём, параметрами запроса или телом. | Используйте новый ключ для нового запроса; повторно используйте ключ только для повтора того же запроса. |
MPBX-IDEMPOTENCY-IN-PROGRESS | 409 | Запрос с этим ключом ещё выполняется. Учитывайте Retry-After. | Повторите через короткое время с тем же ключом. |
MPBX-IDEMPOTENCY-UNAVAILABLE | 503 | У компании слишком много записей Idempotency-Key (или достигнут общий предел установки). Ничего не выполнено. | Учитывайте Retry-After и повторите с тем же ключом; передавайте ключи только в запросах, которым они нужны. |
MPBX-PAYLOAD-TOO-LARGE | 413 | Тело запроса превышает 1 МиБ, которые буферизует слой идемпотентности. | Отправьте тело меньшего размера. |
MPBX-ROUTE-NOT-FOUND | 404 | Ни один маршрут не соответствует пути. Также возвращается для /api/docs, когда переключатель документации в состоянии disabled. | Проверьте путь и версию API. |
MPBX-METHOD-NOT-ALLOWED | 405 | Путь существует, но не для этого HTTP-метода. | Проверьте метод в документации API. |
MPBX-LOCALE-NOT-FOUND | 404 | GET /api/v1/i18n/{locale} для языка, который не установлен. | Используйте один из поставляемых языковых тегов или сначала загрузите языковой пакет. |
MPBX-RATE-LIMITED | 429 | Слишком много попыток входа, обновления, TOTP или обмена при подключении с этого клиента за последнюю минуту (по умолчанию: 10 входов, 60 обновлений и выходов, 10 вызовов TOTP, 10 обменов QR-подключения; http.login_rate_per_min, http.onboarding_rate_per_min и подобные параметры). Клиент — это адрес IPv4 или сеть IPv6 /64 (все адреса одного абонента IPv6 делят один бюджет). Отправляется до проверки пароля. Содержит Retry-After. При наплыве множества разных клиентов, когда таблица ограничителя заполняется заблокированными клиентами, клиенты, которых ещё нет в таблице, тоже получают этот ответ до истечения окон (ограничитель работает по принципу отказа). | Подождите указанное в Retry-After количество секунд. За обратным прокси перечислите его в http.trusted_proxies (или задайте http.trust_forwarded_for), иначе все пользователи делят один адрес. При нескольких узлах API бюджеты разделяются через Valkey. |
MPBX-ME-SESSION-REQUIRED | 403 | PUT /me/language или POST /me/password вызвали с ключом API. Язык или пароль меняет только вошедший человек (FU-WEB04-1). | Войдите и вызовите метод с токеном доступа сессии. |
MPBX-TENANT-HOST-UNKNOWN | 404 | Веб-адрес (Host) имеет вид <slug>.<http.base_domain>, но ни одна компания не имеет такого идентификатора. Возврата к компании по умолчанию нет. | Проверьте адрес; идентификаторы компаний перечислены в разделе «Компании» администрирования. |
MPBX-CROSS-ORIGIN | 403 | POST /api/v1/auth/login, /refresh или /logout пришли со страницы браузера другого источника (заголовок Origin, который не совпадает с адресом этого сервера), например со страницы соседнего поддомена компании или поддельной формы на другом сайте. Cookie обновления для такого запроса никогда не устанавливается и не используется. | Пользователям ничего делать не нужно. Нативные клиенты не отправляют заголовок Origin. |
MPBX-UNSUPPORTED-MEDIA-TYPE | 415 | Маршрут входа (/api/v1/auth/login, /refresh, /logout, /totp/verify) получил тело запроса с Content-Type, отличным от application/json (или application/*+json). Пустое тело (обновление и выход из браузера) не требует Content-Type. Это не позволяет HTML-формам других сайтов (text/plain, форматы кодировки форм) обращаться к маршрутам аутентификации. | Отправьте тело с Content-Type: application/json. |
API настройки (W2-API-01)
Возвращаются маршрутами пользователей, отделов, внутренних номеров, устройств и ролей (docs/guides/config-api.md).
Ошибки ролей и разрешений (MPBX-RBAC-*) и ошибки политики паролей (MPBX-AUTH-PASSWORD-POLICY) описаны в
auth.md.
| Код | HTTP | Значение | Что делать |
|---|---|---|---|
MPBX-API-NOT-CONFIGURED | 503 | Хост не внедрил службы настройки в маршрутизатор API (ошибка развёртывания или подключения) либо маршруты аудита работают без clickhouse.url (записи ждут в очереди исходящих записей Postgres, пока он не задан; см. руководство по аудиту). | Операторы: запустите роль API с настроенной базой данных; клиенты повторяют позже. |
MPBX-INVALID-BODY | 400 | Тело JSON искажено, имеет неверный тип или не содержит обязательного поля. errors[0].message указывает, где. | Исправьте тело; схема и пример есть в документе OpenAPI. |
MPBX-UNSUPPORTED-MEDIA-TYPE | 415 | Маршрут настройки получил тело без Content-Type: application/json (маршруты входа перечислены выше). | Отправьте Content-Type: application/json. |
MPBX-USER-EMAIL-TAKEN | 409 | Другой пользователь компании уже имеет этот адрес электронной почты (сравнение без учёта регистра). | Используйте другой адрес или измените существующего пользователя. |
MPBX-USER-SELF | 409 | Администратор попытался отключить или удалить собственную учётную запись. | Попросите другого администратора. |
MPBX-ACCOUNT-OUTRANKS | 403 | Учётная запись, с которой вы пытались действовать (сбросить пароль или 2FA, отключить, удалить, изменить её адрес электронной почты или отдел), имеет разрешения, которых нет у вас. | Попросите того, у кого есть как минимум такие же разрешения. |
MPBX-ACCOUNT-SYSTEM | 403 | Учётная запись имеет системную роль (Владелец системы или Администратор системы), и вы не имеете более высокого ранга. Владелец системы > Администратор системы > нет роли; другого Владельца системы меняет только Владелец системы; субъекты компании (включая Владельца компании) и ключи API не имеют системного ранга. Охватывает изменение полей, отключение, удаление, сброс пароля или 2FA, назначение и снятие ролей, внутренний номер учётной записи и строки импорта CSV (W1-SEC-01-M1, rbac.md). Также описан в auth.md. | Обратитесь к Владельцу системы (для Администратора системы — к Владельцу системы; для Владельца системы — к другому Владельцу системы), действуя из области системы внутри компании. |
MPBX-EXTENSION-NUMBER-TAKEN | 409 | Другой внутренний номер компании имеет этот номер. | Выберите свободный номер. |
MPBX-EXTENSION-USER-TAKEN | 409 | Пользователь уже владеет внутренним номером (у пользователя не более одного). | Сначала измените или удалите существующий внутренний номер. |
MPBX-EXTENSION-NOT-USER-KIND | 400 | Владелец (user_id) указан для внутреннего номера, вид которого не user. | Уберите user_id или создайте внутренний номер вида user. |
MPBX-DEPARTMENT-NAME-TAKEN | 409 | Другой отдел компании имеет это имя. | Выберите другое имя. |
MPBX-DEPARTMENT-DEFAULT | 409 | Отдел по умолчанию нельзя удалить или перенести в другой отдел (его можно переименовать). | Оставьте его на месте. |
MPBX-DEPARTMENT-NOT-EMPTY | 409 | В отделе ещё есть пользователи или подотделы. | Сначала переместите или удалите их. |
MPBX-DEPARTMENT-CYCLE | 400 | Новый родитель сделал бы отдел своим предком. | Выберите родителя вне поддерева самого отдела. |
MPBX-AVATAR-INVALID | 400 | Фотография профиля не является изображением PNG, JPEG или WebP (проверяются байты, а не имя или Content-Type), повреждена, анимирована, больше 1 МиБ или 2048 на 2048 пикселей либо пуста. Ничего не сохраняется. | Отправьте неподвижное изображение PNG, JPEG или WebP в пределах ограничений. |
MPBX-MEMBERSHIP-PRIMARY | 409 | DELETE /users/{id}/departments/{department_id} указал основной отдел пользователя. | Переместите пользователя через PATCH /users/{id} (department_id). |
MPBX-DEVICE-MAC-TAKEN | 409 | Другое устройство компании имеет этот MAC-адрес. | Проверьте, не дублируется ли устройство, или используйте другой MAC-адрес. |
MPBX-DEVICE-REVOKED | 409 | Устройство отозвано: его нельзя изменить или отозвать повторно, получить для него учётные данные или код подключения. | Создайте новое устройство. |
MPBX-IMPORT-MALFORMED | 400 | Файл CSV пуст, не в UTF-8, содержит незакрытые кавычки, не имеет столбца email либо имеет неизвестные или повторяющиеся столбцы. | Исправьте файл; экспортируйте пользователей, чтобы получить правильный шаблон. |
MPBX-IMPORT-TOO-LARGE | 400 | Файл CSV больше 5 МиБ или содержит более 2000 строк данных. | Разбейте файл. |
MPBX-IMPORT-INVALID | 422 | POST /users/import?dry_run=false нашёл некорректные строки и ничего не записал. errors[] перечисляет до 100 строк с причиной. | Запустите с dry_run=true, исправьте строки в отчёте и примените снова. |
План набора (W2-DP-01)
Возвращаются маршрутами плана набора (/dial-plan/*, /outbound-rules, /inbound-routes,
/calling-profiles); см. руководство по плану набора. Ошибки проверки — это общий MPBX-INVALID-ARGUMENT
(400) с указанием поля; профиль вызовов пользователя также может вернуть MPBX-ACCOUNT-OUTRANKS и
MPBX-ACCOUNT-SYSTEM (см. выше).
| Код | HTTP | Значение | Что делать |
|---|---|---|---|
MPBX-OUTBOUND-RULE-NAME-TAKEN | 409 | Другое правило исходящих вызовов компании имеет это имя. | Выберите другое имя. |
MPBX-INBOUND-ROUTE-TAKEN | 409 | Компания уже направляет этот DID через этот транк либо уже имеет этот общий маршрут (по одному на транк и один на компанию). | Измените существующий маршрут. |
MPBX-INBOUND-BLOCK-EXISTS | 409 | Список блокировки входящих уже содержит этот номер, префикс или анонимную запись для этого DID (W6-TEL-03a). | Измените существующую запись. |
MPBX-INBOUND-CALLER-RULE-NAME-TAKEN | 409 | Другое правило маршрутизации по идентификатору звонящего компании имеет это имя (W6-TEL-03a). | Выберите другое имя. |
MPBX-HOLIDAY-MESSAGE-EXISTS | 409 | У очереди, группы вызова или отдела уже есть праздничное сообщение (W6-TEL-03a). | Измените существующее сообщение. |
MPBX-INBOUND-EXTERNAL-NOT-PERMITTED | 403 | Входящий маршрут или правило идентификатора звонящего ведёт на внешний номер: профиль вызовов и правила исходящих вызовов основного внутреннего номера не разрешают его набор (шлюз против мошенничества, W6-TEL-03a). | Разрешите класс назначения в профиле вызовов основного пользователя или выберите основного пользователя, которому это разрешено. |
MPBX-CALLING-PROFILE-EXISTS | 409 | У компании, отдела или пользователя уже есть профиль вызовов. | Измените существующий профиль (PATCH /calling-profiles/{id}). |
MPBX-EMERGENCY-NUMBER-NAME-TAKEN | 409 | Другой экстренный номер компании имеет это имя (W2-EMR-01). | Выберите другое имя или измените существующий номер (PATCH /emergency-numbers/{id}). |
MPBX-EMERGENCY-NUMBER-APPROVAL | 403 | Номер не входит в известные короткие экстренные номера (911, 112, 999, ...; руководство по экстренным вызовам), либо маршрут добавляет к нему цифры или +, либо маршрут передаёт его в формате, отличном от dialled (e164, e164_digits и national проходят через нумерацию компании, правила набора которой могут превратить его в любой номер). Также возвращается PATCH /dial-plan/settings, когда изменение нумерации (код страны, префиксы, правила набора) изменило бы номер, который передаёт утверждённый маршрут. Экстренный номер обходит все лимиты вызовов, поэтому задать его может только Владелец системы (W2-API-02, замечание PR #126). Уже утверждённые номера сохраняют остальные редактируемые поля. | Попросите Владельца системы задать его, действуя от имени компании (X-Mpbx-Tenant). |
MPBX-EXTENSION-EMERGENCY-NUMBER | 409 | Номер внутреннего номера совпадает с включённым экстренным номером компании: экстренные номера имеют приоритет над внутренними номерами, поэтому внутренний номер никогда не был бы доступен для вызова (W2-API-02, FU-EMR01-8). | Выберите другой номер или сначала выключите экстренный номер. |
Группы вызова (W3-TEL-06)
Возвращаются /ring-groups; см. руководство по группам вызова. Общие условия
(MPBX-EXTENSION-NUMBER-TAKEN для номера группы, MPBX-EXTENSION-EMERGENCY-NUMBER, проверка, 404, 412 и 428)
описаны выше.
| Код | HTTP | Значение | Что делать |
|---|---|---|---|
MPBX-RING-GROUP-NAME-TAKEN | 409 | Другая группа вызова компании имеет это имя. | Выберите другое имя. |
MPBX-RING-GROUP-NO-ANSWER-UNAVAILABLE | 400 | Выведен из употребления (FU-RG-1): голосовая почта принимается как назначение при отсутствии ответа; код больше не возвращается и зарезервирован. | Ничего. |
MPBX-CONFERENCE-ROOM-NAME-TAKEN | 409 | Другая комната конференций компании имеет это имя (W6-TEL-07). | Выберите другое имя. |
Очереди, значения голосовой почты по умолчанию, политики записи (W3-API-02)
Возвращаются /queues, /queue-settings, /voicemail/settings, /recording-settings,
/recording-policies и маршрутами внутренних номеров. Остальные условия (проверка, 404, 412 и 428)
описаны выше; цель записи, которой нет, — это MPBX-REC-INVALID (запись).
| Код | HTTP | Значение | Что делать |
|---|---|---|---|
MPBX-QUEUE-NAME-TAKEN | 409 | Другая очередь компании имеет это имя. | Выберите другое имя. |
MPBX-EXTENSION-HAS-MAILBOX | 409 | В почтовом ящике голосовой почты внутреннего номера есть сообщения или приветствия, поэтому внутренний номер пока нельзя удалить (пустой ящик удаляется вместе с ним). | Сохраните нужное, удалите ящик (DELETE /voicemail/mailboxes/{id}), затем удалите внутренний номер. |
SIP-транки и DID (W2-API-02)
Возвращаются /trunks, /trunks/{id}/dids, /trunk-dids и представлениями уровня системы
/system/trunk-numbers и /system/trunk-approvals; см. руководство по транкам.
Транк, настройку которого отклоняет движок, — это MPBX-TRUNK-INVALID (400, коды ошибок транков).
| Код | HTTP | Значение | Что делать |
|---|---|---|---|
MPBX-TRUNK-NAME-TAKEN | 409 | Другой транк компании имеет это имя. | Выберите другое имя. |
MPBX-TRUNK-DID-OVERLAP | 409 | DID в списке пересекается с другой записью списка или с DID другого транка компании (сообщение называет транк). | Устраните пересечение или сначала переместите номер с другого транка. |
MPBX-TRUNK-DID-TAKEN | 409 | Номер (DID, диапазон, его содержащий, или основной номер транка) принадлежит другой компании в этой системе: номер принадлежит только одной компании. Сообщение никогда не говорит, какая компания, транк или диапазон его занимает; отказ записывается в аудит (trunk.did_refused). | Проверьте номер. Если он ваш, администратор системы находит владельца через GET /system/trunk-numbers и разрешает конфликт. |
MPBX-TRUNK-DID-LIMIT | 409 | Компания имела бы больше 100 000 DID (обеспечивается базой данных). | Удалите неиспользуемые диапазоны или обратитесь к администратору системы. |
MPBX-TRUNK-IN-USE | 409 | Транк нельзя удалить: на него направляет правило исходящих вызовов или экстренный номер либо входящие маршруты ограничены им (errors перечисляет их; GET /trunks/{id}/usage показывает их заранее). | Сначала измените их или удалите с detach_inbound_routes=true, чтобы входящие маршруты действовали для любого транка. |
MPBX-TRUNK-EMERGENCY-ROUTE | 409 | Отключение транка или выключение его исходящих вызовов оставило бы включённый экстренный номер без рабочего маршрута (errors перечисляет его). | Сначала задайте экстренному номеру маршрут через другой транк или выключите его. |
MPBX-TRUNK-APPROVAL-SYSTEM-ONLY | 403 | Утверждать список разрешённых входящих (inbound_acl_approved) может только администратор системы, действующий внутри компании. | Обратитесь к администратору системы; GET /system/trunk-approvals перечисляет ожидающие утверждения. |
MPBX-TRUNK-HOST-NOT-ALLOWED | 403 | Компания не может указать во host, outbound_proxy или registrar внутренний адрес (loopback, частный, link-local, carrier-grade NAT, unique-local и т. п.), заданный напрямую или как имя, которое разрешается в такой адрес (FU-TRK01-12). | Используйте публичный адрес или имя оператора связи; администратор системы может задать внутренний адрес (оператор связи по частной линии). |
Рабочие часы (W3-TEL-05)
Возвращаются маршрутами рабочих часов (/schedules, /schedule-status, /holiday-sets); см. руководство
по рабочим часам. Ошибки проверки (неизвестный часовой пояс, пересекающийся интервал, неверное поле
праздника, переопределение, которое заканчивается в прошлом) — это общий MPBX-INVALID-ARGUMENT (400)
с полем в виде JSON-указателя в errors[].
| Код | HTTP | Значение | Что делать |
|---|---|---|---|
MPBX-SCHEDULE-NAME-TAKEN | 409 | Другое расписание компании имеет это имя. | Выберите другое имя. |
MPBX-SCHEDULE-EXISTS | 409 | У компании (или отдела) уже есть расписание: одно расписание компании и одно на каждый отдел. | Измените существующее расписание (PATCH /schedules/{id}) или создайте расписание вида custom. |
MPBX-HOLIDAY-SET-NAME-TAKEN | 409 | Другой набор праздников компании имеет это имя. | Выберите другое имя. |
MPBX-HOLIDAY-SET-IN-USE | 409 | Набор праздников ещё используется расписанием, поэтому его удаление незаметно превратило бы праздники в обычные дни. | Сначала отсоедините его (PATCH /schedules/{id} с no_holiday_set: true). |
MPBX-HOLIDAY-SET-FULL | 409 | В наборе праздников уже максимально допустимое количество праздников (1000). | Удалите прошедшие праздники или используйте другой набор. |
MPBX-CALENDAR-INVALID | 400 | Загруженный файл не является файлом iCalendar (нет BEGIN:VCALENDAR, не UTF-8), больше 1 МиБ или содержит более 2000 событий. | Экспортируйте календарь заново в формате .ics или разбейте его. |
История изменений и откат (W4-ADM-02)
Возвращаются POST /api/v1/config-history/{id}/revert (и показываются как revert.code в
GET /api/v1/config-history/{id}); см. руководство по истории изменений. Отказ операции, которую вызывает откат
(проверка, MPBX-RBAC-FORBIDDEN, MPBX-RBAC-ESCALATION, MPBX-EXTENSION-NUMBER-TAKEN, 412 и т. д.),
возвращается как есть.
| Код | HTTP | Значение | Что делать |
|---|---|---|---|
MPBX-HISTORY-CONFLICT | 409 | Более поздние изменения затрагивают те же поля объекта (conflicts[], вид newer_change, перечисляет их с различиями), либо более позднее изменение другого объекта упоминает значение, которое установило изменение (вид dependent_change), либо поле больше не имеет того значения, которое ему дало изменение, и ни одна запись истории не объясняет почему (вид value_changed, с expected и actual). Ничего не изменено. | Посмотрите перечисленные изменения. Откатите более новые сначала (от новых к старым) или задайте значение вручную. |
MPBX-HISTORY-NOT-REVERTIBLE | 409 | У этого вида изменения нет обратного хода: удаление (кроме снятого назначения роли; запись показывает последние значения, чтобы объект можно было создать заново), объект больше не существует, поле без обработчика отката либо откат ничего не изменит. | Создайте или измените объект обычными операциями. |
MPBX-HISTORY-SECRET-FIELD | 409 | Изменение затронуло пароль, секрет двухфакторной аутентификации или учётные данные устройства. Старое значение нигде не сохраняется, поэтому восстановить его нельзя. | Задайте пароль заново (сброс пароля) или повторно зарегистрируйте устройство или 2FA. |
MPBX-HISTORY-NO-SNAPSHOT | 409 | Запись сохранила только имена изменённых полей (изменение прошло путь, который ещё не передаёт значения), поэтому восстанавливать нечего. | Измените объект вручную. |
MPBX-HISTORY-ALREADY-REVERTED | 409 | Более позднее изменение уже откатило это, и такой откат ещё действует. | Откатите запись отката, если хотите вернуть изменение. |
WebSocket событий и click-to-call (W3-API-01)
Возвращаются GET /api/v1/events (до обновления — как problem+json; после — в кадрах error и кодах закрытия)
и POST /api/v1/calls/click-to-call. Руководство: events-ws.md.
| Код | HTTP / закрытие | Значение | Что делать |
|---|---|---|---|
MPBX-NOT-IMPLEMENTED | 501 | Контракт маршрута опубликован, но его поведение в этом выпуске недоступно. Ни один маршрут сейчас так не отвечает (POST /api/v1/calls/click-to-call отвечал так до MVP-GAP-04; без движка вызовов теперь отвечает 503 MPBX-CALL-ENGINE-UNAVAILABLE, calls.md). Вызывающий был аутентифицирован, тело проверено. | Не повторяйте. Разрабатывайте по описанию OpenAPI; маршрут начнёт работать в одном из следующих выпусков без изменений запроса или ответа. |
MPBX-EVENTS-WS-UPGRADE-REQUIRED | 426 | Обычный HTTP-запрос пришёл на GET /api/v1/events. | Откройте WebSocket (обновление HTTP/1.1, версия 13). |
MPBX-EVENTS-WS-BAD-TOPIC | 400 / кадр error | Имя темы не входит в список call, leg, queue, presence, voicemail, config, audit. | Исправьте имя. |
MPBX-EVENTS-WS-BAD-CURSOR | 400 / кадр error | cursor не является идентификатором события. | Передайте cursor события, которое вы получили. |
MPBX-EVENTS-WS-CURSOR-TOO-LATE | кадр error | cursor пришёл в subscribe после первого. | Переподключитесь с курсором. |
MPBX-EVENTS-WS-BAD-MESSAGE | кадр error, закрытие 1008 | Кадр клиента не является JSON известного op либо является двоичным. Более 10 таких кадров закрывают сокет. | Отправляйте subscribe, unsubscribe, ping (и auth первым, если заголовок не передан). |
MPBX-EVENTS-WS-NOT-AUTHENTICATED | кадр error, закрытие 4401 | Первый кадр сокета без учётных данных в заголовке не был auth. | Сначала отправьте {"op":"auth","token":...}. |
MPBX-EVENTS-WS-AUTH-TIMEOUT | закрытие 4401 | Кадр auth не пришёл за 5 с. | Отправьте его сразу после подключения. |
MPBX-EVENTS-WS-AUTH-FAILED | закрытие 4401 / 4403 | Учётные данные в кадре auth отклонены; предшествующий кадр error содержит причину (MPBX-AUTH-*, MPBX-TENANT-*). | Войдите снова. |
MPBX-EVENTS-WS-ALREADY-AUTHENTICATED | кадр error | Кадр auth на уже аутентифицированном сокете. | Ничего; сокет продолжает работать. |
MPBX-EVENTS-WS-CREDENTIAL-ENDED | закрытие 4401 | Токен доступа истёк, был отозван или пользователь отключён; обнаруживается периодической проверкой (каждые 60 с). | Обновите токен и переподключитесь с курсором. |
MPBX-EVENTS-WS-TOO-MANY | 429 / закрытие 4429 | Слишком много открытых подключений событий для этого пользователя или ключа (по умолчанию 20), для компании (5 000) или для всей установки (10 000). Также причина закрытия соединения, закрытого, чтобы освободить место: сокет, ожидающий аутентификации, из сети с наибольшим числом таких сокетов, либо самое новое подключение компании с наибольшим числом таких подключений, когда другой компании нужно место в заполненной установке. Ответ 429 содержит Retry-After. | Закрывайте неиспользуемые сокеты; используйте один сокет на клиент; переподключайтесь с курсором после задержки Retry-After. |
MPBX-EVENTS-WS-IDLE | закрытие 4408 | Клиент ничего не отправлял, даже pong, 60 с. | Отвечайте на ping (браузеры делают это сами) или отправьте {"op":"ping"}; переподключитесь с курсором. |
MPBX-EVENTS-WS-SLOW-CONSUMER | закрытие 1013 | Клиент читает кадры недостаточно быстро; сервер никогда не буферизует без ограничения. | Читайте непрерывно; переподключитесь с курсором. |
Языковые пакеты и переопределение строк (W4-L10N-04)
Возвращаются /api/v1/i18n/packs, /i18n/overrides и /i18n/strings (руководство).
MPBX-LOCALE-NOT-FOUND (см. выше) также возвращается маршрутами администрирования для языка,
который компания не поставляет и не загружала.
| Код | HTTP | Значение | Что делать |
|---|---|---|---|
MPBX-LOCALE-TAG-INVALID | 400 | Языковой тег не имеет вид language[-Script][-REGION][-variant] из букв и цифр (например, sv, pt-PT, sr-Latn). | Используйте тег BCP 47; поставляются: en, es-MX, pt-BR, fr, de, it, ru, zh-Hans и ja. |
MPBX-LOCALE-RTL-UNSUPPORTED | 400 | Язык пишется справа налево (арабский, иврит, персидский, урду и т. д.). Клиенты не имеют раскладки справа налево (DECISIONS Round 6). | В версии v1 не поддерживается. |
MPBX-LOCALE-PACK-INVALID | 422 | Пакет не прошёл проверку, и ничего не сохранено. errors[] перечисляет до 100 проблем с ключом: неизвестный ключ (которого нет в английском исходнике), некорректный синтаксис ICU, заполнители, отличающиеся от английских, разметка (<b>, <script>), управляющие или двунаправленные символы, сообщение длиннее 2000 символов, более 10 000 ключей, пустой пакет либо отсутствующее name для нового языка. | Исправьте перечисленные ключи и загрузите снова. Чтобы увидеть те же проверки локально, выполните mpbx i18n validate <file>. |
MPBX-LOCALE-PACK-EXISTS | 409 | POST /i18n/packs для языка, у которого уже есть пакет. | Выполните GET пакета, чтобы получить его ETag, и замените его командой PUT /i18n/packs/{locale}. |
MPBX-LOCALE-PACK-LIMIT | 409 | У компании уже 30 загруженных языков. | Удалите язык, который не используете. |
MPBX-LOCALE-OVERRIDE-INVALID | 422 | Ключа переопределения нет в английском исходнике, либо текст содержит некорректный синтаксис ICU, заполнители, отличные от английских, разметку, управляющие символы, пуст или длиннее 2000 символов. | Исправьте ключ или текст; errors[] указывает, что именно. |
MPBX-LOCALE-OVERRIDE-LIMIT | 409 | У языка уже 5000 переопределений. | Удалите ненужные переопределения. |
Учётные данные SIP, профиль SIP и подключение по QR-коду (W2-API-03)
Возвращаются /devices/{id}/credentials, /sip-settings, /sip-lock, /unlock, /onboarding-token,
маршрутами /me/sip-profile и /me/devices, а также /onboarding/exchange (руководство). Без служб SIP
(ошибка подключения) эти маршруты отвечают MPBX-API-NOT-CONFIGURED (см. выше). Устройство на внутреннем
номере учётной записи, которой вы не можете управлять, — это MPBX-ACCOUNT-OUTRANKS или MPBX-ACCOUNT-SYSTEM
(см. выше).
| Код | HTTP | Значение | Что делать |
|---|---|---|---|
MPBX-DEVICE-CHANGED | 409 | Устройство (или ваш внутренний номер) изменилось, пока выпускались новые учётные данные, например оно было отозвано или изменено в тот же момент. Ничего не изменено, и ни один пароль не действует. | Перечитайте устройство и повторите попытку. |
MPBX-DEVICE-LIMIT | 409 | У вас уже максимально допустимое количество активных устройств на собственном внутреннем номере (по умолчанию 10). | Отзовите устройство, которым больше не пользуетесь (POST /me/devices/{id}/revoke), или обратитесь к администратору. |
MPBX-SIP-SESSION-REQUIRED | 403 | Маршрут /me/sip-profile или /me/devices вызвали с ключом API. Ваши собственные устройства SIP управляются только из вошедшей сессии. | Войдите (POST /auth/login) и используйте токен доступа; администраторы используют маршруты /devices. |
MPBX-CDR-SESSION-REQUIRED | 403 | GET /me/calls или /me/calls/{id} вызвали с ключом API. Ваши вызовы читаются из вошедшей сессии; история по всей компании — это GET /cdr. | Войдите и используйте токен доступа либо используйте GET /cdr с правом call_history:read. |
MPBX-SIP-NO-EXTENSION | 404 | У вас нет внутреннего номера, поэтому нет профиля SIP и устройств. | Попросите администратора назначить вам внутренний номер. |
MPBX-ONBOARDING-TOKEN-INVALID | 401 | Код подключения неизвестен по этому адресу, просрочен (по умолчанию 10 минут), уже использован, заменён более новым кодом для того же устройства, либо его устройство отозвано или пользователь отключён. Один ответ для всех случаев. | Запросите новый QR-код или ссылку и отсканируйте её в пределах срока действия по адресу, который она называет. |
Автонастройка настольных телефонов (W4-DEV-01)
Возвращаются маршрутами /devices/{id}/provisioning и /provisioning/... (руководство).
Маршруты /prov/..., к которым обращаются телефоны, не имеют тела ошибки: каждый отказ — это пустой ответ 404
(чтобы никто не мог узнать, что именно было неверно), клиенты, превысившие бюджет, получают
429 MPBX-RATE-LIMITED, а URL, защищённый digest, отвечает 401 с заголовком WWW-Authenticate: Digest.
| Код | HTTP | Значение | Что делать |
|---|---|---|---|
MPBX-PROVISIONING-NO-MAC | 409 | У устройства нет пригодного MAC-адреса (его нет или он такой, какого у телефона быть не может: все нули, групповой адрес). | Задайте MAC у устройства (PATCH /devices/{id}) и повторите попытку. |
MPBX-PROVISIONING-EXISTS | 409 | У устройства уже есть профиль автонастройки. | Измените его через PATCH или выпустите новый URL командой POST .../regenerate. |
MPBX-PROVISIONING-NOT-FOUND | 404 | У устройства нет профиля автонастройки. | Создайте его командой POST /devices/{id}/provisioning. |
MPBX-PROVISIONING-LINK-LIMIT | 409 | У устройства уже есть 5 неиспользованных неистёкших подписанных ссылок автонастройки (W6-DEV-01b). | Отзовите их (DELETE /devices/{id}/provisioning/links) или дождитесь истечения срока, затем выпустите новую. |
Контакты (MVP-GAP-05)
| Код | HTTP | Значение | Что делать |
|---|---|---|---|
MPBX-CONTACT-NUMBER-TAKEN | 409 | Другой контакт той же книги (общего справочника компании или ваших личных контактов) уже имеет этот номер телефона; цифры phone идентифицируют контакт. | Измените существующий контакт или используйте другой номер. Импорт CSV обновляет такой контакт вместо ошибки. |
MPBX-CONTACT-LIMIT | 409 | В книге было бы больше допустимого: 200 000 контактов в общем справочнике компании или 20 000 личных контактов на пользователя. Импорт, который превысил бы лимит, откатывается целиком. | Удалите ненужные контакты. |
MPBX-CONTACT-IMPORT-BUSY | 409 | Другой импорт той же книги (общего справочника компании или личных контактов того же пользователя) ещё выполняется либо сервер уже выполняет два импорта контактов одновременно (все компании вместе; в ответе тогда есть Retry-After). | Дождитесь завершения и повторите попытку. |
MPBX-CONTACT-NO-PERSONAL | 403 | Учётная запись не является пользователем компании, от имени которой выполняется запрос (администратор системы, который вошёл в компанию), поэтому личных контактов в ней у неё нет. | Используйте общий справочник компании или войдите как пользователь компании. |
Импорт контактов из CSV также отвечает кодами импорта MPBX-IMPORT-MALFORMED (неверный заголовок,
кавычки или кодировка, загрузка зависла или прервалась), MPBX-IMPORT-TOO-LARGE (более 100 000 строк или
64 МиБ) и MPBX-IMPORT-INVALID (422: некорректные строки без skip_invalid).
Web push для браузеров (W6-RLY-WEB)
Возвращаются GET /me/web-push и PUT / DELETE /me/devices/{id}/web-push (руководство). Эти маршруты
принимают только вошедшую сессию (ключ API даёт MPBX-SIP-SESSION-REQUIRED, см. выше); устройство, которое
не является вашим действующим устройством, — это MPBX-NOT-FOUND; более 10 изменений в минуту — это
MPBX-RATE-LIMITED (429, Retry-After).
| Код | HTTP | Значение | Что делать |
|---|---|---|---|
MPBX-WEB-PUSH-INVALID | 400 | Тело не является подпиской Push API: адрес конечной точки не является URL https:// (или длиннее 1024 символов), либо keys.p256dh (65 байт) или keys.auth (16 байт) отсутствует или не является base64url нужного размера. | Отправьте PushSubscription.toJSON() подписки, созданной с application_server_key из GET /me/web-push. |
MPBX-WEB-PUSH-NOT-BROWSER | 409 | Устройство — это телефон, мобильное приложение которого зарегистрировало push-токен; подписка браузера заменила бы его. | Зарегистрируйте подписку для собственного устройства браузера (устройство веб-софтфона, POST /me/devices). |
MPBX-WEB-PUSH-REFUSED | 422 | Ретранслятор push не доставляет сообщения в службу push этого браузера (она не входит в известные публичные службы push Chrome, Edge, Firefox и Safari; код ретранслятора RELAY-WEB-ENDPOINT-REFUSED). | Используйте текущий evergreen-браузер; вызовы всё равно звонят, пока открыт MonoPbx. |
MPBX-WEB-PUSH-UNAVAILABLE | 503 | Этот сервер сейчас не может отправить web push: нет ретранслятора push (изолированная среда или не зарегистрирован), ретранслятор недоступен, ретранслятор не обслуживает браузеры, льготный период лицензии истёк или регистрация не удалась. Тогда GET /me/web-push отвечает available: false. | Повторите позже; оператор проверяет состояние ретранслятора push (docs/guides/push-wake.md). |
MPBX-ACT-CODE-INVALID | 400 | Код ручной активации некорректен, неизвестен, уже использован, просрочен или привязан к другой установке (код ретранслятора RELAY-ENROLL-CODE-INVALID). | Проверьте код; запросите у MonoPbx новый, привязанный к этой установке (mpbx activate --show-key). |
MPBX-ACT-RELAY-UNREACHABLE | 503 | Ручная активация не смогла связаться с ретранслятором push либо ручная активация выключена (relay.enroll = false или не задан MPBX_RELAY_INSTANCE_KEY). | Разрешите исходящий HTTPS к ретранслятору и повторите попытку; вызовы не затронуты. |
MPBX-ACT-RATE-LIMITED | 503 | Более 5 попыток ручной активации (правильных или нет) за 15 минут на этой установке (W7-SEC-01-C1 ACT-1). | Подождите несколько минут и введите код ещё раз; сначала проверьте его на опечатки. |
MPBX-OAUTH-INVALID-REQUEST | 400 | Запрос OAuth клиента MCP некорректен (отсутствует параметр, неверный верификатор или вызов PKCE). Конечная точка токенов отвечает invalid_request. | Исправьте запрос клиента (docs/guides/mcp.md). |
MPBX-OAUTH-INVALID-CLIENT | 400/401 | Неизвестный клиент MCP либо URI перенаправления не зарегистрирован для него. Конечная точка авторизации отвечает обычным 400 и никогда не перенаправляет. | Зарегистрируйте клиента заново (POST /oauth/register) с точным URI перенаправления. |
MPBX-OAUTH-INVALID-GRANT | 400 | Код авторизации или токен обновления неизвестен, израсходован, просрочен, отозван либо не соответствует клиенту, URI перенаправления, верификатору или ресурсу. Израсходованный код или повторно предъявленный заменённый токен обновления отзывают разрешение. | Начните авторизацию заново. |
MPBX-OAUTH-INVALID-SCOPE | 400 | Ни одна из запрошенных областей не является разрешением, которым обладает вошедший пользователь. | Запросите разрешения, которыми обладает пользователь, либо попросите администратора назначить роль. |
MPBX-OAUTH-INVALID-TARGET | 400 | resource не является конечной точкой MCP этого сервера (https://<host>/mcp). | Используйте ресурс из /.well-known/oauth-protected-resource/mcp. |
MPBX-OAUTH-INVALID-REDIRECT-URI | 400 | Зарегистрированный URI перенаправления должен быть https:// или http:// на адресе loopback, без фрагмента. | Исправьте регистрацию клиента. |
MPBX-OAUTH-TOKEN-INVALID | 401 | Токен доступа MCP неизвестен, просрочен, отозван, принадлежит другой компании или выдан для другого ресурса. /mcp отвечает 401 с заголовком WWW-Authenticate. | Обновите токен или авторизуйтесь заново. |
MPBX-OAUTH-TOO-MANY-CLIENTS | 400 | У компании уже 500 зарегистрированных клиентов MCP. | Оператор удаляет неиспользуемых клиентов (FU-W9-AI-13-2). |
MPBX-STORAGE-QUOTA-EXCEEDED | 507 | Компания использовала больше 100 % квоты хранилища: новые записи вызовов, вложения чата и SMS/MMS, медиа факсов и загрузки отклоняются (руководство). Вызовы никогда не блокируются, голосовая почта работает до 110 %, ничего не удаляется. | Освободите место (удалите старые записи или файлы, сократите срок хранения) или попросите администратора системы увеличить квоту; административное оповещение StorageQuotaExceeded уже создано. |
MPBX-DISPOSITION-NOT-PARTICIPANT | 403 | PUT /me/agent/calls/{id}/disposition: агент не участвовал в вызове (его запись истории вызовов не называет его, CC-AGENT-006, G-020). | Отмечайте только вызовы, которые обрабатывали вы. |
MPBX-DISPOSITION-CALL-PENDING | 409 | PUT /me/agent/calls/{id}/disposition: вызова ещё нет в истории вызовов (запись создаётся по завершении вызова). | Повторите попытку через несколько секунд. |