Códigos de error comunes (mpbx-common)

Cada mpbx_common::Error lleva un código estable. La capa de API asigna el tipo a un estado HTTP y usa el código como sufijo type del problema RFC 9457. Los mensajes nunca contienen secretos.

Código	Tipo	Significado	Qué hacer
MPBX-INVALID-ARGUMENT	invalid_argument	Un valor está mal formado, por ejemplo un ID que no es un UUIDv7.	Corrija la solicitud.
MPBX-NOT-FOUND	not_found	La entidad no existe o no es visible en su empresa.	Revise el ID y la empresa.
MPBX-CONFLICT	conflict	Conflicto de estado, incluida una discrepancia de versión del bloqueo optimista.	Vuelva a leer e intente de nuevo.
MPBX-UNAUTHENTICATED	unauthenticated	No hay credenciales válidas.	Inicie sesión de nuevo.
MPBX-PERMISSION-DENIED	permission_denied	Está autenticado, pero el rol no tiene el permiso.	Pida ayuda a un administrador.
MPBX-UNAVAILABLE	unavailable	Una dependencia (Postgres, Valkey, ClickHouse, almacén de objetos) no está disponible. Se puede reintentar.	Reintente; revise el estado de la dependencia.
MPBX-INTERNAL	internal	Condición inesperada.	Repórtelo con la línea del registro.
MPBX-CONFIG	config	Problema genérico de configuración.	Corrija mpbx.toml o el entorno.
MPBX-SIP-DOMAIN-UNSET	config / unavailable	La instalación no tiene dominio SIP (el realm de digest con el que se registran los teléfonos). Un proceso con rol SIP se niega a iniciar; un pod de API responde 503 en las rutas que emiten credenciales SIP.	Defina http.base_domain o sip.install_domains en la configuración de un pod para su primer inicio, o termine el asistente de configuración con una dirección ([setup] fqdn). Se guarda una sola vez en la base de datos y lo comparten todos los pods (setup-wizard.md).
MPBX-CONFIG-INVALID	config	La configuración combinada no se pudo interpretar: clave desconocida, tipo incorrecto o dirección no válida (incluida una URL [ice] con esquema incorrecto, credenciales o un transport no válido, o ice.turn_ttl_secs fuera de 60..=86400). El mensaje nombra la clave.	Corrija la clave indicada; los errores de escritura son errores a propósito.
MPBX-CONFIG-FILE-NOT-FOUND	config	El archivo de configuración indicado explícitamente (argumento de ruta o MPBX_CONFIG) no existe.	Corrija la ruta.
MPBX-CONFIG-MISSING	config	Falta una configuración obligatoria (por ejemplo postgres.url). El mensaje nombra la variable de entorno. También: ice.turn_urls está definido pero falta el secreto de instalación TURN_SECRET o tiene menos de 24 caracteres (nat-turn.md).	Defínala en mpbx.toml o con variables de entorno; para TURN, pase TURN_SECRET desde mpbx init (nunca invente uno).
MPBX-CONFIG-UNKNOWN-FLAG	config	[features] nombra una bandera que no existe.	Revise la ortografía con las banderas conocidas.
MPBX-TENANT-MISMATCH	permission_denied	La credencial (token o clave de API) pertenece a otra empresa que la que la solicitud indica (host, encabezado X-Mpbx-Tenant o un id de empresa en la solicitud).	Inicie sesión en la dirección de su empresa, o use una credencial de esa empresa.
MPBX-TENANT-CLAIM-INVALID	unauthenticated	Las declaraciones de empresa del token son inconsistentes: alcance de empresa sin tid, o alcance de sistema con un tid.	Inicie sesión de nuevo; repórtelo si se repite (error al emitir tokens).
MPBX-TENANT-SYSTEM-REQUIRED	permission_denied	Una operación de toda la instalación (empresas, configuración de la instalación, respaldos, actualizaciones) se llamó con una credencial de alcance de empresa.	Use una cuenta de Propietario o Administrador del sistema.
MPBX-TENANT-REQUIRED	permission_denied	Una credencial de alcance de sistema llamó una operación de empresa sin seleccionar la empresa.	Envíe el encabezado X-Mpbx-Tenant: <id de empresa> (la acción queda auditada).
MPBX-APIKEY-MALFORMED	unauthenticated	La clave de API no tiene el formato mpbx_k1_<empresa>_<id de clave>_<secreto>. La clave nunca se muestra.	Copie la clave completa de nuevo, o cree una nueva.