Códigos de error de almacenamiento (mpbx-storage, PostgreSQL)

Códigos que genera mpbx_storage::pg (W1-PBX-02). Los tipos se asignan a estados HTTP en la capa de API como en los códigos comunes. Los mensajes indican como máximo una restricción; nunca contienen valores de filas, así que ningún dato personal ni secreto llega a los registros ni a las respuestas de la API.

Código	Tipo	Significado	Qué hacer
MPBX-VERSION-MISMATCH	conflict	Bloqueo optimista: la fila cambió desde que la leyó (el mensaje indica la version esperada y la actual).	Recargue el objeto y vuelva a aplicar su cambio.
MPBX-PG-DUPLICATE	conflict	Una regla de unicidad rechazó la escritura, por ejemplo un número de extensión ya usado en esta empresa. El mensaje indica la restricción.	Elija otro valor.
MPBX-PG-REFERENCE	invalid_argument	Una referencia apunta a una fila que no existe en esta empresa, o una fila todavía está referenciada y no se puede eliminar.	Revise el id referenciado y la empresa; elimine primero los dependientes.
MPBX-PG-CONSTRAINT	invalid_argument	Un valor rompe una regla CHECK o NOT NULL (slug incorrecto, formato de número incorrecto), o se modificó una versión publicada de un flujo de llamada.	Corrija el valor. Las versiones publicadas de los flujos son inmutables: publique una versión nueva.
MPBX-PG-RETRY	conflict	Falla de serialización o interbloqueo entre transacciones concurrentes. Se puede reintentar.	Reintente la operación.
MPBX-PG-UNAVAILABLE	unavailable	No se puede contactar a Postgres, se está reiniciando, o el pool no tuvo una conexión libre en 5 s. Se puede reintentar.	Revise el estado de Postgres y postgres.max_connections.
MPBX-PG-TENANT-DENIED	permission_denied	La seguridad a nivel de fila o un privilegio de tabla rechazó la instrucción (SQLSTATE 42501): una transacción de empresa intentó escribir una fila de otra empresa, mover una fila a otra empresa, o tocar una tabla de toda la instalación (configuración de la instalación, la lista de empresas). También se genera cuando el rol de inicio de sesión no puede cambiar a mpbx_tenant/mpbx_system.	Un error o un ataque en el código que llama: el código de empresa solo debe usar repositorios TenantTx. Si aparece al iniciar, otorgue los roles: GRANT mpbx_tenant, mpbx_system TO <rol de inicio de sesión>; (como superusuario).
MPBX-PG-QUERY	internal	Cualquier otro error de base de datos. El mensaje contiene el SQLSTATE.	Repórtelo con la línea del registro.
MPBX-PG-URL-INVALID	config	postgres.url no se interpreta como una URL postgres://. La URL nunca se imprime.	Corrija MPBX__POSTGRES__URL o mpbx.toml.
MPBX-PG-LOGIN-SCOPE-UNSAFE	config	Al iniciar, un inicio de sesión por ámbito (postgres.tenant_url / postgres.system_url, FU-PBX10-M1) tiene más derechos de los que permite su ámbito: el inicio de sesión de empresa es superusuario, tiene BYPASSRLS, es miembro de mpbx_system o no es miembro de mpbx_tenant; o el inicio de sesión de sistema es superusuario, tiene BYPASSRLS o no es miembro de mpbx_system.	Use los roles mpbx_tenant_login / mpbx_system_login de las migraciones sin cambios (docs/guides/database-logins.md).
MPBX-PG-MIGRATION-FAILED	internal	Falló una migración y se revirtió su transacción; el esquema no cambió.	Lea la causa en el registro, corrija el estado de la base de datos o repórtelo como error.
MPBX-PG-MIGRATION-MODIFIED	config	Se editó una migración ya aplicada después de publicarse (la suma de verificación no coincide). Las migraciones solo se agregan.	Entregue el cambio como una migración nueva y restaure el archivo original.
MPBX-PG-SCHEMA-AHEAD	config	La base de datos tiene migraciones que este binario no conoce: se inició un binario más antiguo contra un esquema más nuevo. No se cambió nada.	Ejecute la versión más nueva, o revierta con la copia de la base de datos anterior a la actualización (mpbx rollback).
MPBX-PG-MIGRATION-DIRTY	internal	Una ejecución anterior se detuvo a la mitad de una migración no transaccional.	Restaure desde un respaldo. (Todas las migraciones entregadas son transaccionales, así que esto no debería ocurrir.)

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

Los mensajes nunca contienen la URL del servidor, las credenciales ni los valores de las filas.

Código	Tipo	Significado	Qué hacer
MPBX-CH-UNAVAILABLE	unavailable	No se puede contactar a ClickHouse, se está reiniciando, sobrecargado, o una inserción agotó el tiempo. Se puede reintentar. El escritor no hace fallar a quien llama: vuelca el lote a Valkey (bus:ch_spill) y lo reproduce cuando ClickHouse responde.	Revise el estado de ClickHouse. Observe mpbx_ch_spill_backlog_batches; vuelve a 0 después de la recuperación.
MPBX-CH-QUERY	internal	ClickHouse rechazó una consulta o inserción por un motivo distinto a la disponibilidad. El mensaje contiene el número de error del servidor. Una inserción rechazada se mueve al flujo de cartas muertas bus:ch_dead (mpbx_ch_rows_dead_total) en lugar de bloquear la cola de volcado.	Revise bus:ch_dead, corrija el esquema o el escritor, y repórtelo como error.
MPBX-CH-CONFIG	config	Falta clickhouse.url o no es una URL http(s)://, o clickhouse.database no contiene solo letras, dígitos y guiones bajos.	Corrija MPBX__CLICKHOUSE__URL / MPBX__CLICKHOUSE__DATABASE o mpbx.toml.
MPBX-CH-MIGRATION-FAILED	internal	Falló una instrucción de migración de ClickHouse. ClickHouse no tiene DDL transaccional, así que es posible que se hayan aplicado instrucciones anteriores de la misma migración; todas las instrucciones son idempotentes, así que ejecute mpbx migrate --ch otra vez después de corregir la causa.	Lea la causa en el mensaje, corrija el estado del servidor y ejecute de nuevo.
MPBX-CH-MIGRATION-MODIFIED	config	Se editó un archivo de migración de ClickHouse ya aplicado (la suma de verificación no coincide).	Entregue el cambio como una migración nueva y restaure el archivo original.
MPBX-CH-SCHEMA-AHEAD	config	La base de datos de ClickHouse tiene migraciones que este binario no conoce: se inició un binario más antiguo contra un esquema más nuevo. No se cambió nada.	Ejecute la versión más nueva.
MPBX-CH-WRITER-CLOSED	unavailable	Se escribió una fila después de cerrar el escritor por lotes (apagado en curso).	No es un problema del operador; el proceso se está deteniendo.

Valkey y ClickHouse (aislamiento de empresas, W1-PBX-10)

Código	Tipo	Significado	Qué hacer
MPBX-VALKEY-TENANT-KEY	internal	Se entregó un manejador de Valkey con ámbito de empresa (TenantValkey) una clave fuera del prefijo t:{tenant_id}: de la empresa (clave de otra empresa o clave de toda la instalación). No se leyó ni escribió nada.	Un error en el código que llama: construya las claves con TenantValkey::keys().
MPBX-CH-TENANT-MISMATCH	invalid_argument	Una fila de ClickHouse entregada al escritor de una empresa ya indica otra empresa en tenant_id. Se rechaza el lote.	Un error en el código que llama: nunca copie tenant_id desde la entrada; el escritor lo define a partir del contexto de la empresa.