Коды ошибок хранилища (mpbx-storage, PostgreSQL)

Коды, которые возвращает mpbx_storage::pg (W1-PBX-02). Типы ошибок соответствуют HTTP-статусам на уровне API, как в общих кодах. Сообщения называют не более чем ограничение; они никогда не содержат значения строк, поэтому персональные данные и секреты не попадают в журналы и ответы API.

Код	Вид	Значение	Что делать
MPBX-VERSION-MISMATCH	conflict	Оптимистичная блокировка: строка изменилась после вашего чтения (в сообщении указаны ожидаемая и текущая version).	Перезагрузите объект и повторите изменение.
MPBX-PG-DUPLICATE	conflict	Правило уникальности отклонило запись, например номер внутреннего номера уже используется в этой компании. В сообщении назван ограничение.	Выберите другое значение.
MPBX-PG-REFERENCE	invalid_argument	Ссылка указывает на строку, которой нет в этой компании, либо строка ещё на что-то ссылается и не может быть удалена.	Проверьте идентификатор ссылки и арендатора; сначала удалите зависимые объекты.
MPBX-PG-CONSTRAINT	invalid_argument	Значение нарушает правило CHECK или NOT NULL (неверный slug, неверный формат номера) либо изменена опубликованная версия схемы вызовов.	Исправьте значение. Опубликованные версии схем неизменяемы: опубликуйте новую версию.
MPBX-PG-RETRY	conflict	Ошибка сериализации или взаимная блокировка параллельных транзакций. Можно повторить.	Повторите операцию.
MPBX-PG-UNAVAILABLE	unavailable	Postgres недоступен, перезапускается, либо в пуле за 5 с не нашлось свободного соединения. Можно повторить.	Проверьте состояние Postgres и postgres.max_connections.
MPBX-PG-TENANT-DENIED	permission_denied	Защита на уровне строк или право на таблицу отклонили оператор (SQLSTATE 42501): транзакция компании попыталась записать строку другой компании, перенести строку в другую компанию или изменить общесистемную таблицу (настройки установки, список компаний). Также возвращается, если роль входа не может переключиться на mpbx_tenant/mpbx_system.	Ошибка или атака в вызывающем коде: код компании должен использовать только репозитории TenantTx. Если ошибка возникает при запуске, выдайте роли: GRANT mpbx_tenant, mpbx_system TO <login role>; (от суперпользователя).
MPBX-PG-QUERY	internal	Любая другая ошибка базы данных. В сообщении указан SQLSTATE.	Сообщите о ней вместе со строкой журнала.
MPBX-PG-URL-INVALID	config	postgres.url не разбирается как URL postgres://. Сам URL никогда не выводится.	Исправьте MPBX__POSTGRES__URL или mpbx.toml.
MPBX-PG-LOGIN-SCOPE-UNSAFE	config	При запуске отдельный вход для области (postgres.tenant_url / postgres.system_url, FU-PBX10-M1) имеет больше прав, чем допускает его область: вход арендатора является суперпользователем, имеет BYPASSRLS, входит в mpbx_system или не входит в mpbx_tenant; либо системный вход является суперпользователем, имеет BYPASSRLS или не входит в mpbx_system.	Используйте роли mpbx_tenant_login / mpbx_system_login из миграций без изменений (docs/guides/database-logins.md).
MPBX-PG-MIGRATION-FAILED	internal	Миграция завершилась ошибкой, её транзакция откатана; схема не изменилась.	Найдите причину в журнале, исправьте состояние базы данных или сообщите об ошибке.
MPBX-PG-MIGRATION-MODIFIED	config	Уже применённая миграция была изменена после выпуска (контрольная сумма не совпадает). Миграции только добавляются.	Выпустите изменение как новую миграцию и восстановите исходный файл.
MPBX-PG-SCHEMA-AHEAD	config	В базе данных есть миграции, которых не знает этот бинарный файл: старый бинарный файл запущен против более новой схемы. Ничего не изменено.	Запустите более новый релиз или откатитесь к снимку базы данных до обновления (mpbx rollback).
MPBX-PG-MIGRATION-DIRTY	internal	Предыдущий запуск остановился на середине нетранзакционной миграции.	Восстановите из резервной копии. (Все поставляемые миграции транзакционны, поэтому этого не должно происходить.)

ClickHouse (mpbx_storage::ch, W1-PBX-03)

Сообщения никогда не содержат URL сервера, учётные данные или значения строк.

Код	Вид	Значение	Что делать
MPBX-CH-UNAVAILABLE	unavailable	ClickHouse недоступен, перезапускается, перегружен или вставка превысила время ожидания. Можно повторить. Писатель не завершает вызов с ошибкой: он переносит пакет в Valkey (bus:ch_spill) и повторяет его, когда ClickHouse снова отвечает.	Проверьте состояние ClickHouse. Следите за mpbx_ch_spill_backlog_batches; после восстановления значение возвращается к 0.
MPBX-CH-QUERY	internal	ClickHouse отклонил запрос или вставку по причине, не связанной с доступностью. В сообщении указан номер ошибки сервера. Отклонённая вставка перемещается в поток недоставленных bus:ch_dead (mpbx_ch_rows_dead_total), чтобы не блокировать очередь переноса.	Изучите bus:ch_dead, исправьте схему или писатель, сообщите об ошибке.
MPBX-CH-CONFIG	config	clickhouse.url отсутствует или не является URL http(s)://, либо clickhouse.database содержит символы, отличные от букв, цифр и подчёркиваний.	Исправьте MPBX__CLICKHOUSE__URL / MPBX__CLICKHOUSE__DATABASE или mpbx.toml.
MPBX-CH-MIGRATION-FAILED	internal	Оператор миграции ClickHouse завершился ошибкой. У ClickHouse нет транзакционного DDL, поэтому более ранние операторы той же миграции могли примениться; все операторы идемпотентны, поэтому после устранения причины выполните mpbx migrate --ch снова.	Прочитайте причину в сообщении, исправьте состояние сервера и запустите снова.
MPBX-CH-MIGRATION-MODIFIED	config	Уже применённый файл миграции ClickHouse был изменён (контрольная сумма не совпадает).	Выпустите изменение как новую миграцию и восстановите исходный файл.
MPBX-CH-SCHEMA-AHEAD	config	В базе данных ClickHouse есть миграции, которых не знает этот бинарный файл: старый бинарный файл запущен против более новой схемы. Ничего не изменено.	Запустите более новый релиз.
MPBX-CH-WRITER-CLOSED	unavailable	Строка записана после того, как пакетный писатель был закрыт (идёт завершение работы).	Это не проблема оператора: процесс останавливается.

Valkey и ClickHouse (изоляция арендаторов, W1-PBX-10)

Код	Вид	Значение	Что делать
MPBX-VALKEY-TENANT-KEY	internal	Дескриптору Valkey компании (TenantValkey) передан ключ вне префикса t:{tenant_id}: компании (ключ другой компании или общесистемный ключ). Ничего не прочитано и не записано.	Ошибка в вызывающем коде: формируйте ключи через TenantValkey::keys().
MPBX-CH-TENANT-MISMATCH	invalid_argument	Строка ClickHouse, переданная писателю компании, уже указывает в tenant_id на другую компанию. Пакет отклонён.	Ошибка в вызывающем коде: никогда не копируйте tenant_id из входных данных; писатель задаёт его из контекста арендатора.