Códigos de error de autenticación (mpbx-auth)

Se generan en el núcleo de autenticación (W1-AUTH-01) y en el motor RBAC (W1-AUTH-02). Los tipos se asignan a estados HTTP como en los códigos comunes: unauthenticated es 401, permission_denied 403, invalid_argument 400, not_found 404, conflict 409, unavailable 503, y config e internal 500. Los mensajes nunca contienen una contraseña, un token, un hash, una clave ni una dirección de correo. Guía: autenticación.

Código	Tipo	Significado	Qué hacer
MPBX-AUTH-INVALID-CREDENTIALS	unauthenticated	El inicio de sesión falló. El mismo código cubre un correo desconocido, una contraseña incorrecta, una cuenta bloqueada tras demasiados fallos, un usuario deshabilitado y una empresa suspendida, así que la respuesta no revela qué cuentas existen. También lo devuelve un cambio de contraseña cuando la contraseña actual es incorrecta.	Revise el correo y la contraseña. Después de auth.lockout.max_failures fallos, la red queda bloqueada para esa cuenta durante auth.lockout.lockout_secs (se duplica con cada bloqueo seguido; W4-AUTH-01: el bloqueo se aplica a la red del cliente de donde vinieron los fallos, una dirección IPv4 o un /64 de IPv6, así que el propietario puede seguir entrando desde otro lugar); espere, use otra red, o pida a un administrador que la desbloquee (POST /api/v1/users/{id}/unlock, o mpbx user unlock <empresa> <correo> en el servidor). Se acepta un código de recuperación (recovery_code) en lugar del código TOTP, y uno incorrecto o ya usado responde MPBX-AUTH-TOTP-INVALID.
MPBX-AUTH-TOKEN-INVALID	unauthenticated	El token de acceso falta, está mal formado, no es EdDSA, está firmado con una clave desconocida o retirada (por ejemplo un token de otra instalación, o uno anterior al periodo de gracia de una rotación de claves), tiene una firma incorrecta, o tiene un emisor o una audiencia incorrectos.	Inicie sesión de nuevo. Los servicios que verifican tokens deben cargar el conjunto JWK actual de la instalación.
MPBX-AUTH-TOKEN-EXPIRED	unauthenticated	El token de acceso venció (o todavía no es válido).	Use el token de actualización para obtener un token de acceso nuevo. Si ocurre justo después de iniciar sesión, revise los relojes (auth.clock_leeway_secs).
MPBX-AUTH-TOKEN-REVOKED	unauthenticated	El token de acceso o su sesión fueron revocados (cierre de sesión, cambio de contraseña, reutilización del token de actualización, administrador).	Inicie sesión de nuevo.
MPBX-AUTH-REFRESH-INVALID	unauthenticated	El token de actualización está mal formado, es desconocido, venció (sin usar durante auth.refresh_idle_ttl_secs, o la sesión es más antigua que auth.session_max_age_secs), su sesión terminó, o el usuario o la empresa están deshabilitados.	Inicie sesión de nuevo.
MPBX-AUTH-REFRESH-REUSED	unauthenticated	Se presentó de nuevo un token de actualización que ya se había canjeado, después de la ventana de gracia (auth.refresh_reuse_grace_secs, 20 s) o siendo más antiguo que el token inmediato anterior. Eso significa que dos partes tienen la misma sesión (un token robado, o un cliente que envió dos veces la misma actualización), así que se revocó toda la sesión y sus tokens de acceso se pusieron en la lista de denegados. Dentro de la ventana de gracia, el token anterior devuelve el par ya emitido.	Inicie sesión de nuevo. Los clientes deben serializar las llamadas de actualización (una en vuelo por sesión) y guardar siempre el token de actualización más reciente. Si se repite, investigue el dispositivo.
MPBX-AUTH-PASSWORD-POLICY	invalid_argument	Una contraseña nueva incumple la política de contraseñas. El mensaje enumera las reglas incumplidas por clave: too_short, too_long, too_few_character_classes, invalid_characters, common, contains_user_info, repetitive.	Elija otra contraseña; una frase de varias palabras es lo más fácil.
MPBX-AUTH-KEY-INVALID	config	El material de clave JWT falta o es incorrecto: MPBX_JWT_SIGNING_KEY, MPBX_JWT_PUBLIC_KEY o MPBX_JWT_KID sin definir o mal formados, una clave pública que no corresponde a la clave de firma, una clave débil, o una entrada mal formada de MPBX_JWT_PREVIOUS_KEYS. El mensaje indica la variable, nunca el valor.	Restaure los secretos de la instalación desde un respaldo, o genérelos con mpbx init en una instalación nueva.
MPBX-AUTH-CONFIG-INVALID	config	Un valor de la sección de configuración [auth] está fuera de rango (el mensaje indica cuál y el rango permitido).	Corrija mpbx.toml o la variable de entorno MPBX__AUTH__*.
MPBX-AUTH-HASH	internal	Falló el cálculo del hash de la contraseña o el generador de números aleatorios del sistema operativo.	Revise el host (memoria para argon2, fuente de entropía) y repórtelo con la línea del registro.
MPBX-AUTH-REVOCATION-UNAVAILABLE	unavailable	No se pudo leer Valkey para verificar la lista de tokens denegados. Las solicitudes fallan en modo cerrado en lugar de aceptar un token posiblemente revocado. Se puede reintentar.	Revise el estado de Valkey.
MPBX-AUTH-PRINCIPAL-INACTIVE	unauthenticated	El token de acceso o la clave de API son válidos, pero su usuario está deshabilitado o eliminado, o la empresa está suspendida. Se verifica en cada solicitud, así que deshabilitar a un usuario termina su acceso de inmediato.	Pida a un administrador que vuelva a habilitar la cuenta o la empresa.
MPBX-APIKEY-INVALID	unauthenticated	La clave de API es desconocida en la empresa que nombra, fue revocada, venció, o su secreto es incorrecto. Un solo código para todos los casos, para que un sondeo no aprenda nada. Una clave cuya parte de empresa fue editada también se rechaza aquí: la clave se busca solo dentro de la empresa que nombra la cadena.	Cree una clave nueva (Administración, claves de API) y reemplace la anterior en todas partes.
MPBX-KIOSK-INVALID	unauthenticated	El token del kiosco de pantalla (X-Kiosk-Token) falta, es desconocido, fue revocado o venció. Un solo código para todos los casos. La revocación se aplica a la siguiente solicitud.	Cree un enlace nuevo de kiosco (Administración, enrutamiento de colas, kioscos de pantalla).
MPBX-RBAC-FORBIDDEN	permission_denied	El solicitante no tiene el permiso que necesita la operación (el ámbito indicado en el documento OpenAPI), o lo tiene solo para otros departamentos distintos a los del recurso. El mensaje indica el permiso.	Pida a un administrador un rol que lo conceda; GET /api/v1/me enumera lo que usted tiene y dónde.
MPBX-RBAC-ESCALATION	permission_denied	Asignar un rol, definir un rol personalizado o elegir ámbitos de clave de API entregaría un permiso que el solicitante no tiene para ese ámbito (empresa o departamento). Nadie puede conceder más de lo que tiene.	Pida a alguien que tenga el permiso en ese ámbito (normalmente el Propietario) que lo haga.
MPBX-RBAC-UNKNOWN-PERMISSION	invalid_argument	Una clave de permiso no está en el catálogo, o es un permiso del sistema usado en un rol de empresa o en una clave de API.	Use las claves listadas en la guía de RBAC.
MPBX-RBAC-BUILTIN-READONLY	conflict	Los roles integrados (Usuario, Recepcionista, Supervisor, Administrador de departamento, Gerente, Propietario) no se pueden renombrar, cambiar ni eliminar.	Cree un rol personalizado con los permisos que necesita.
MPBX-RBAC-LAST-OWNER	conflict	El cambio dejaría a la empresa sin un Propietario de toda la empresa, o a la instalación sin un Propietario del sistema.	Asigne primero el rol a otra persona.
MPBX-RBAC-NOT-FOUND	not_found	El rol, la asignación de rol o el departamento no existe en esta empresa (los ids de otra empresa se comportan como si no existieran).	Revise el id; liste los roles de la empresa con la API de roles.
MPBX-RBAC-SYSTEM-ROLE-REQUIRED	permission_denied	Un token de ámbito de sistema (o una solicitud para obtenerlo) para un usuario que no tiene ni Administrador del sistema ni Propietario del sistema, por ejemplo después de revocarle el rol.	Inicie sesión de nuevo con un token de empresa, o pida el rol a un Propietario del sistema.
MPBX-ACCOUNT-SYSTEM	permission_denied	Un principal que no tiene un rango superior a una cuenta con rol de sistema (Propietario del sistema o Administrador del sistema) intentó cambiarla: sus campos, estado, eliminación, contraseña, 2FA, bloqueo, asignaciones de rol, roles de sistema, extensión o claves de API. Propietario del sistema > Administrador del sistema > ninguno; solo un Propietario del sistema cambia a otro Propietario del sistema; un principal de empresa o una clave de API no tiene rango de sistema (W1-SEC-01-M1, rbac.md).	Pida a un Propietario del sistema.
MPBX-AUTH-TOTP-REQUIRED	unauthenticated	El correo y la contraseña eran correctos, pero la cuenta tiene activada la autenticación de dos factores TOTP y el inicio de sesión no envió totp_code.	Pida al usuario el código de 6 dígitos de su aplicación de autenticación y repita el inicio de sesión con el mismo correo y contraseña más totp_code.
MPBX-AUTH-TOTP-INVALID	unauthenticated	El totp_code (o recovery_code) es incorrecto, pertenece a una ventana de tiempo equivocada (se tolera un paso de 30 segundos de desfase), o ya se usó una vez; o el segundo factor de la cuenta se bloquea tras auth.lockout.max_failures códigos incorrectos en la ventana desde cualquier red (revisión PR #109: un presupuesto para toda la cuenta; entonces el código no se verifica y un código de recuperación no se gasta). Cuenta como un inicio de sesión fallido hacia el bloqueo de red, igual que una contraseña incorrecta.	Escriba el código actual; revise el reloj del teléfono. Después de varios códigos incorrectos, espere auth.lockout.lockout_secs (se duplica por cada bloqueo seguido) o pida a un administrador que limpie los bloqueos de inicio de sesión.
MPBX-AUTH-TOTP-CODE-MISMATCH	invalid_argument	POST /api/v1/auth/totp/verify: el código no coincide con el secreto pendiente. TOTP permanece desactivado hasta que un código coincida. También es la respuesta al primer código de un registro durante el inicio de sesión y al desactivar TOTP cuando el código es incorrecto o el segundo factor de la cuenta está bloqueado (el mismo presupuesto para toda la cuenta que MPBX-AUTH-TOTP-INVALID).	Vuelva a escanear el secreto desde POST /api/v1/auth/totp/enroll y envíe el código actual.
MPBX-AUTH-TOTP-ALREADY-ENABLED	conflict	Se pidió el registro cuando TOTP ya está activado para la cuenta. Un segundo factor activo nunca se reemplaza en silencio.	Un administrador restablece primero el factor (administración de usuarios), y luego vuelva a registrarlo.
MPBX-AUTH-TOTP-NOT-ENROLLED	conflict	POST /api/v1/auth/totp/verify sin un registro pendiente (nunca se registró, o ya se confirmó), o un registro para una cuenta que no tiene contraseña local.	Llame primero a POST /api/v1/auth/totp/enroll.
MPBX-AUTH-TOTP-UNAVAILABLE	unavailable	El servidor no tiene el llavero de secretos (MPBX_MASTER_KEY no cargada), así que los secretos TOTP no se pueden sellar ni abrir. El inicio de sesión de una cuenta con TOTP activado falla en modo cerrado con este código.	Inicie el servidor con los secretos de la instalación de mpbx init.
MPBX-AUTH-BUSY	unavailable	Todas las ranuras de cálculo de hash de contraseña siguieron ocupadas durante 2 segundos, así que la contraseña no se verificó (HTTP 503 con Retry-After). Argon2 cuesta unos 19 MiB y una CPU por verificación, así que el servidor ejecuta como máximo dos a la vez por CPU; este es el límite del trabajo de hash sin autenticar durante una avalancha de inicios de sesión. No se verificó ni cambió nada de la cuenta, y el fallo no cuenta hacia el bloqueo. Se puede reintentar.	Reintente después de un momento. Si ocurre sin una avalancha, revise las advertencias MPBX-AUTH-BUSY del registro y la CPU del host.
MPBX-AUTH-TOTP-ENROLMENT-REQUIRED	unauthenticated	La contraseña era correcta, pero la política de dos factores de la empresa cubre la cuenta (/api/v1/two-factor-policy: todos, o uno de sus roles) y todavía no tiene una aplicación de autenticación. No se abrió ninguna sesión; nada se registra en silencio.	Explique la política al usuario, llame a POST /api/v1/auth/totp/enrolment con el mismo correo y contraseña para obtener el secreto (código QR), y luego inicie sesión con el primer código (totp_code): eso confirma la aplicación de autenticación y devuelve los códigos de recuperación una sola vez.
MPBX-AUTH-TOTP-ENROLMENT-NOT-REQUIRED	conflict	POST /api/v1/auth/totp/enrolment para una cuenta que la política no cubre (aun así puede registrarse después de iniciar sesión).	Inicie sesión y luego regístrese en Seguridad de la cuenta.
MPBX-AUTH-TOTP-ENROLMENT-CODE-INVALID	unauthenticated	POST /api/v1/auth/totp/enrolment sin el código de un solo uso enviado por correo con POST /api/v1/auth/totp/enrolment/code, o con un código incorrecto, vencido (10 minutos), ya usado, reemplazado por uno más nuevo, quemado tras 5 intentos incorrectos, o enviado a una dirección que la cuenta ya no tiene (FU-AUTH01-L3). Un código incorrecto también cuenta hacia el bloqueo del inicio de sesión.	Pida un código nuevo (POST /api/v1/auth/totp/enrolment/code) y escriba el del correo más reciente.
MPBX-AUTH-TOTP-ENROLMENT-CODE-THROTTLED	conflict (HTTP 429)	POST /api/v1/auth/totp/enrolment/code menos de un minuto después del último código, o después de 5 códigos para la cuenta (o su dirección) o 20 desde la red del cliente dentro de una hora. Se define Retry-After.	Espere, y luego use el código más reciente que ya está en el buzón.
MPBX-AUTH-TOTP-ENROLMENT-MAIL-UNAVAILABLE	unavailable	No se puede enviar por correo el código de registro: la empresa no tiene proveedor de correo (y la instalación no tiene [email.smtp]), o el proveedor rechazó el correo. El código se anuló; nada se registró.	Configure el proveedor de correo (Configuración, Correo), o un administrador levanta la política de dos factores para la cuenta hasta que esté configurado.
MPBX-AUTH-TOTP-POLICY	conflict	POST /api/v1/auth/totp/disable para una cuenta que la política de dos factores de la empresa cubre.	Pida a un administrador que cambie la política o restablezca el factor (POST /api/v1/users/{id}/two-factor-reset).
MPBX-AUTH-REAUTH-FAILED	permission_denied	Un cambio sensible de la propia cuenta pide la contraseña actual (registro y eliminación de TOTP, nuevos códigos de recuperación, restablecer la propia contraseña mediante las rutas de usuario) y era incorrecta, o el inicio de sesión desde esta red está bloqueado. Cuenta hacia el bloqueo como un inicio de sesión incorrecto. HTTP 403, para que un cliente no lo confunda con una sesión vencida.	Escriba la contraseña actual.
MPBX-AUTH-INVITE-INVALID	unauthenticated	El enlace de invitación es desconocido, venció, ya se usó, fue reemplazado por una invitación más reciente, o la cuenta fue deshabilitada o ya tiene contraseña. Un solo código para todos, así que la respuesta no revela nada.	Pida al administrador que envíe una invitación nueva (POST /api/v1/users/{id}/invitation).
MPBX-AUTH-INVITE-ONBOARDED	conflict	Se pidió una invitación para una cuenta que ya tiene contraseña.	Use el restablecimiento de contraseña en su lugar.
MPBX-AUTH-INVITE-HOST	conflict	POST /api/v1/users/{id}/invitation se envió a una dirección web que no es la propia de la empresa (en modo Multiempresa, la dirección de otra empresa, o la dirección de la instalación para una empresa que no es la predeterminada). El enlace del correo se construye a partir de esa dirección, así que no llevaría a la empresa.	Envíe la invitación desde la dirección web propia de la empresa (<empresa>.<dominio del PBX>). Detrás de un proxy u otro nombre público, envíela desde el nombre público que abren las personas y conserve el Host original (vea la guía de autenticación, FU-AUTH01-L5).

Configuración inicial y elevación de permisos (W4-WEB-06)

Se generan en las rutas de configuración (/api/v1/setup/*) y en POST /api/v1/auth/elevate. Guía: asistente de configuración inicial.

Código	Tipo	Significado	Qué hacer
MPBX-SETUP-TOKEN-INVALID	unauthenticated	El token del enlace de configuración es incorrecto o está incompleto, o esta instalación no tiene token de configuración (MPBX_SETUP_TOKEN_SHA256 sin definir o mal formado). Un solo código para todos, para que un sondeo no aprenda nada. Los intentos rechazados tienen límite de frecuencia por red del cliente y se registran en la bitácora de auditoría de la instalación (setup.refused).	Use el enlace más reciente que imprimió el instalador. Emita uno nuevo con mpbx-ctl setup-url (VM) o borrando los valores MPBX_SETUP_TOKEN_* y ejecutando mpbx init otra vez (Compose, Kubernetes); el enlace anterior deja de funcionar.
MPBX-SETUP-TOKEN-EXPIRED	unauthenticated	El token es correcto, pero ya pasó MPBX_SETUP_TOKEN_EXPIRES_AT (24 horas después de mpbx init, por omisión).	Emita un enlace nuevo como arriba.
MPBX-SETUP-COMPLETE	conflict	Ya existe el primer Propietario del sistema: la configuración se completó con el enlace (el token se gastó), o la base de datos ya tiene un Propietario del sistema (una restauración, una instalación sembrada). Las rutas del token de configuración nunca crean otro propietario, sin importar qué secretos de instalación conserve. También es la respuesta de los pasos de configuración con sesión iniciada una vez terminado el asistente.	Inicie sesión como de costumbre. Para agregar administradores, un Propietario del sistema asigna roles en la consola.
MPBX-SETUP-OWNER-PENDING	conflict	Un Propietario del sistema ya se creó con el enlace y espera su código de autenticación.	Termínelo (POST /api/v1/setup/owner/confirm), obtenga un código QR nuevo (POST /api/v1/setup/owner/totp), o empiece de nuevo (POST /api/v1/setup/owner/reset).
MPBX-SETUP-NO-OWNER-PENDING	conflict	Se intentó confirmar, reiniciar o restablecer al propietario cuando ninguno espera confirmación.	Cree primero al propietario (POST /api/v1/setup/owner).
MPBX-SETUP-CREDENTIALS-INVALID	unauthenticated	El correo o la contraseña no coinciden con el Propietario del sistema creado con el enlace. Una contraseña incorrecta cuenta hacia el bloqueo de inicio de sesión de esa cuenta.	Escriba el correo y la contraseña elegidos en el primer paso, o empiece de nuevo.
MPBX-AUTH-STEP-UP-UNAVAILABLE	conflict	POST /api/v1/auth/elevate: el acceso a toda la instalación se confirma con un código de la aplicación de autenticación de la cuenta, y esta cuenta no tiene ninguna confirmada.	Configure el inicio de sesión de dos factores en Seguridad de la cuenta y luego vuelva a intentarlo.