Códigos de error de la API (mpbx-api)

Estos códigos se devuelven en el miembro code de los cuerpos application/problem+json (vea docs/api/CONVENTIONS.md). Los códigos genéricos por tipo (MPBX-NOT-FOUND, MPBX-INVALID-ARGUMENT, ...) están en common.md.

Código	HTTP	Significado	Qué hacer
MPBX-INVALID-QUERY	400	Un parámetro limit, sort o filter no es válido: campo desconocido o no filtrable, operador incorrecto, tipo de valor equivocado, demasiados filtros. errors[].field nombra el parámetro.	Corrija el parámetro; vea los campos permitidos en la documentación del endpoint.
MPBX-INVALID-CURSOR	400	El cursor está mal formado o se emitió para otro filtro u orden.	Comience desde la primera página; nunca edite ni reutilice cursores entre consultas.
MPBX-PRECONDITION-REQUIRED	428	Un PUT, PATCH o DELETE no tenía el encabezado If-Match.	Haga GET del recurso y envíe su ETag como If-Match.
MPBX-PRECONDITION-FAILED	412	If-Match no coincide: el recurso cambió desde que lo leyó.	Haga GET de nuevo, aplique su cambio y reintente con el nuevo ETag.
MPBX-IDEMPOTENCY-KEY-INVALID	400	Idempotency-Key está vacío, tiene más de 255 caracteres, no es ASCII visible, o se envió más de una vez.	Envíe una clave de 1 a 255 caracteres ASCII visibles (sirve un UUID).
MPBX-IDEMPOTENCY-KEY-REUSED	422	El mismo cliente ya usó la clave en esta ruta con otra ruta, consulta o cuerpo.	Use una clave nueva para una solicitud nueva; reutilice una clave solo para reintentar la misma solicitud.
MPBX-IDEMPOTENCY-IN-PROGRESS	409	Una solicitud con esta clave todavía se está ejecutando. Respete Retry-After.	Reintente pronto con la misma clave.
MPBX-IDEMPOTENCY-UNAVAILABLE	503	La empresa tiene demasiados registros de Idempotency-Key (o se alcanzó el límite de la instalación). No se ejecutó nada.	Respete Retry-After y reintente con la misma clave; envíe claves solo en las solicitudes que las necesitan.
MPBX-PAYLOAD-TOO-LARGE	413	El cuerpo de la solicitud supera 1 MiB almacenados en búfer por la capa de idempotencia.	Envíe un cuerpo más pequeño.
MPBX-ROUTE-NOT-FOUND	404	Ninguna ruta coincide con la ruta. También se devuelve para /api/docs cuando el interruptor de documentación está disabled.	Revise la ruta y la versión de la API.
MPBX-METHOD-NOT-ALLOWED	405	La ruta existe, pero no para este método HTTP.	Revise el método en la documentación de la API.
MPBX-LOCALE-NOT-FOUND	404	GET /api/v1/i18n/{locale} para un idioma que no está instalado.	Use una de las etiquetas de idioma incluidas o suba primero el paquete de idioma.
MPBX-RATE-LIMITED	429	Demasiados intentos de inicio de sesión, renovación, TOTP o intercambio de incorporación desde este cliente en el último minuto (valores predeterminados: 10 inicios de sesión, 60 renovaciones y cierres de sesión, 10 llamadas TOTP, 10 intercambios de incorporación por QR; http.login_rate_per_min, http.onboarding_rate_per_min y similares). Un cliente es una dirección IPv4 o una red IPv6 /64 (todas las direcciones de un mismo suscriptor IPv6 comparten el presupuesto). Se envía antes de verificar cualquier contraseña. Incluye Retry-After. En una inundación de clientes distintos que llena la tabla del limitador con clientes limitados, los clientes que todavía no están en la tabla también reciben esta respuesta hasta que expiren las ventanas (el limitador falla cerrado).	Espere los segundos de Retry-After. Detrás de un proxy inverso, indíquelo en http.trusted_proxies (o defina http.trust_forwarded_for); de lo contrario, todos los usuarios comparten una dirección. Con varios nodos de API, los presupuestos se comparten a través de Valkey.
MPBX-ME-SESSION-REQUIRED	403	PUT /me/language o POST /me/password se llamó con una clave de API. Solo una persona que inició sesión puede cambiar su propio idioma o contraseña (FU-WEB04-1).	Inicie sesión y llame con el token de acceso de la sesión.
MPBX-TENANT-HOST-UNKNOWN	404	La dirección web (Host) es <slug>.<http.base_domain>, pero ninguna empresa tiene ese identificador. No hay alternativa a la empresa predeterminada.	Revise la dirección; los identificadores de empresa aparecen en el área de administración de empresas.
MPBX-CROSS-ORIGIN	403	POST /api/v1/auth/login, /refresh o /logout llegó desde una página de navegador de otro origen (un encabezado Origin que no es la dirección propia de este servidor), por ejemplo una página de un subdominio de otra empresa o un formulario falsificado en otro sitio. La cookie de renovación nunca se establece ni se usa para esta solicitud.	Ninguna para los usuarios. Los clientes nativos no envían el encabezado Origin.
MPBX-UNSUPPORTED-MEDIA-TYPE	415	Una ruta de inicio de sesión (/api/v1/auth/login, /refresh, /logout, /totp/verify) recibió un cuerpo cuyo Content-Type no es application/json (ni application/*+json). Un cuerpo vacío (renovación y cierre de sesión desde el navegador) no necesita Content-Type. Esto evita que los formularios HTML de otros sitios (text/plain, codificaciones de formulario) lleguen a las rutas de autenticación.	Envíe el cuerpo con Content-Type: application/json.

API de configuración (W2-API-01)

Se devuelven en las rutas de usuarios, departamentos, extensiones, dispositivos y roles (docs/guides/config-api.md). Los errores de rol y de permiso (MPBX-RBAC-*) y de la política de contraseñas (MPBX-AUTH-PASSWORD-POLICY) están en auth.md.

Código	HTTP	Significado	Qué hacer
MPBX-API-NOT-CONFIGURED	503	El host no inyectó los servicios de configuración en el enrutador de la API (un error de despliegue o de cableado), o las rutas de auditoría se ejecutan sin clickhouse.url (los registros esperan en la bandeja de salida de Postgres hasta que se configure; vea la guía de auditoría).	Operadores: inicien el rol de API con la base de datos configurada; los clientes reintentan más tarde.
MPBX-INVALID-BODY	400	El cuerpo JSON está mal formado, tiene un tipo incorrecto o le falta un campo obligatorio. errors[0].message indica dónde.	Corrija el cuerpo; el documento OpenAPI tiene el esquema y un ejemplo.
MPBX-UNSUPPORTED-MEDIA-TYPE	415	Una ruta de configuración recibió un cuerpo sin Content-Type: application/json (las rutas de inicio de sesión se listan arriba).	Envíe Content-Type: application/json.
MPBX-USER-EMAIL-TAKEN	409	Otro usuario de la empresa ya tiene este correo electrónico (la comparación no distingue mayúsculas).	Use otra dirección, o cambie el usuario existente.
MPBX-USER-SELF	409	El administrador intentó deshabilitar o eliminar su propia cuenta.	Pida a otro administrador que lo haga.
MPBX-ACCOUNT-OUTRANKS	403	La cuenta sobre la que intentó actuar (restablecer su contraseña o 2FA, deshabilitarla, eliminarla, cambiar su correo o su departamento) tiene permisos que usted no tiene.	Pida a alguien que tenga al menos los mismos permisos.
MPBX-ACCOUNT-SYSTEM	403	La cuenta tiene un rol de sistema (Propietario del sistema o Administrador del sistema) y usted no tiene un rango superior. Propietario del sistema > Administrador del sistema > ninguno, y solo un Propietario del sistema cambia a otro Propietario del sistema; los principales de empresa (incluido el Propietario de una empresa) y las claves de API no tienen rango de sistema. Cubre cambios de campos, deshabilitar, eliminar, restablecer contraseña o 2FA, asignar o quitar roles, la extensión de la cuenta y las filas de importación CSV (W1-SEC-01-M1, rbac.md). También en auth.md.	Pida a un Propietario del sistema (para un Administrador del sistema, un Propietario del sistema; para un Propietario del sistema, otro Propietario del sistema), actuando desde el alcance de sistema dentro de la empresa.
MPBX-EXTENSION-NUMBER-TAKEN	409	Otra extensión de la empresa tiene este número.	Elija un número libre.
MPBX-EXTENSION-USER-TAKEN	409	El usuario ya es dueño de una extensión (un usuario tiene como máximo una).	Cambie o elimine primero la extensión existente.
MPBX-EXTENSION-NOT-USER-KIND	400	Se asignó un dueño (user_id) a una extensión cuyo tipo no es user.	Omita user_id, o cree una extensión de tipo user.
MPBX-DEPARTMENT-NAME-TAKEN	409	Otro departamento de la empresa tiene este nombre.	Elija otro nombre.
MPBX-DEPARTMENT-DEFAULT	409	El departamento predeterminado no se puede eliminar ni mover bajo otro departamento (sí se puede renombrar).	Déjelo en su lugar.
MPBX-DEPARTMENT-NOT-EMPTY	409	El departamento todavía tiene usuarios o subdepartamentos.	Muévalos o elimínelos primero.
MPBX-DEPARTMENT-CYCLE	400	El nuevo padre convertiría al departamento en su propio ancestro.	Elija un padre fuera del subárbol del propio departamento.
MPBX-AVATAR-INVALID	400	La foto de perfil no es una imagen PNG, JPEG o WebP (se revisan los bytes, no el nombre ni el Content-Type), está dañada, es animada, pesa más de 1 MiB o mide más de 2048 por 2048 píxeles, o está vacía. No se guarda nada.	Envíe una imagen fija PNG, JPEG o WebP dentro de los límites.
MPBX-MEMBERSHIP-PRIMARY	409	DELETE /users/{id}/departments/{department_id} nombró el departamento principal del usuario.	Mueva al usuario con PATCH /users/{id} (department_id) en su lugar.
MPBX-DEVICE-MAC-TAKEN	409	Otro dispositivo de la empresa tiene esta dirección MAC.	Revise si hay un dispositivo duplicado, o use otra MAC.
MPBX-DEVICE-REVOKED	409	El dispositivo está revocado: no se puede cambiar ni revocar de nuevo, obtener credenciales ni un token de incorporación.	Cree un dispositivo nuevo.
MPBX-IMPORT-MALFORMED	400	El archivo CSV está vacío, no es UTF-8, tiene comillas sin cerrar, le falta la columna email o tiene columnas desconocidas o repetidas.	Corrija el archivo; exporte los usuarios para obtener una plantilla correcta.
MPBX-IMPORT-TOO-LARGE	400	El archivo CSV pesa más de 5 MiB o tiene más de 2000 filas de datos.	Divida el archivo.
MPBX-IMPORT-INVALID	422	POST /users/import?dry_run=false encontró filas no válidas y no escribió nada. errors[] enumera hasta 100 filas con el motivo.	Ejecute con dry_run=true, corrija las filas del informe y aplique de nuevo.

Plan de marcación (W2-DP-01)

Se devuelven en las rutas del plan de marcación (/dial-plan/*, /outbound-rules, /inbound-routes, /calling-profiles); vea la guía del plan de marcación. Los errores de validación son el MPBX-INVALID-ARGUMENT genérico (400) con el campo; el perfil de llamadas de un usuario también puede devolver MPBX-ACCOUNT-OUTRANKS y MPBX-ACCOUNT-SYSTEM (arriba).

Código	HTTP	Significado	Qué hacer
MPBX-OUTBOUND-RULE-NAME-TAKEN	409	Otra regla de salida de la empresa tiene este nombre.	Elija otro nombre.
MPBX-INBOUND-ROUTE-TAKEN	409	La empresa ya enruta este DID en este troncal, o ya tiene este comodín general (uno por troncal y uno para la empresa).	Cambie la ruta existente.
MPBX-INBOUND-BLOCK-EXISTS	409	La lista de bloqueo de entrada ya contiene este número, prefijo o entrada anónima para este DID (W6-TEL-03a).	Cambie la entrada existente.
MPBX-INBOUND-CALLER-RULE-NAME-TAKEN	409	Otra regla de enrutamiento por identificador de llamada de la empresa tiene este nombre (W6-TEL-03a).	Elija otro nombre.
MPBX-HOLIDAY-MESSAGE-EXISTS	409	La cola, el grupo de timbrado o el departamento ya tiene un mensaje de día festivo (W6-TEL-03a).	Cambie el mensaje existente.
MPBX-INBOUND-EXTERNAL-NOT-PERMITTED	403	Una ruta de entrada o una regla de identificador de llamada hacia un número externo: el perfil de llamadas y las reglas de salida de la extensión principal no permiten marcarlo (control de fraude telefónico, W6-TEL-03a).	Permita la clase de destino en el perfil de llamadas del principal, o elija un principal que pueda marcarlo.
MPBX-CALLING-PROFILE-EXISTS	409	La empresa, el departamento o el usuario ya tiene un perfil de llamadas.	Cambie el perfil existente (PATCH /calling-profiles/{id}).
MPBX-EMERGENCY-NUMBER-NAME-TAKEN	409	Otro número de emergencia de la empresa tiene este nombre (W2-EMR-01).	Elija otro nombre, o cambie el número existente (PATCH /emergency-numbers/{id}).
MPBX-EMERGENCY-NUMBER-APPROVAL	403	El número no es uno de los códigos cortos de emergencia conocidos (911, 112, 999, ...; guía de emergencias), o una ruta antepone dígitos o + a él, o una ruta lo envía en un formato distinto de dialled (e164, e164_digits y national pasan por la numeración de la empresa, cuyas reglas de marcado pueden convertirlo en cualquier número). También lo devuelve PATCH /dial-plan/settings cuando un cambio de numeración (código de país, prefijos, reglas de marcado) cambiaría el número que envía una ruta aprobada. Un número de emergencia omite todos los límites de llamadas, así que solo el Propietario del sistema puede definirlo (W2-API-02, revisión de PR #126). Los números ya aprobados conservan editables sus demás campos.	Pida al Propietario del sistema que lo defina, actuando en la empresa (X-Mpbx-Tenant).
MPBX-EXTENSION-EMERGENCY-NUMBER	409	El número de la extensión es un número de emergencia habilitado de la empresa: los números de emergencia se deciden antes que las extensiones, así que la extensión nunca podría recibir llamadas (W2-API-02, FU-EMR01-8).	Elija otro número, o deshabilite primero el número de emergencia.

Grupos de timbrado (W3-TEL-06)

Se devuelven en /ring-groups; vea la guía de grupos de timbrado. Las condiciones compartidas (MPBX-EXTENSION-NUMBER-TAKEN para el número del grupo, MPBX-EXTENSION-EMERGENCY-NUMBER, validación, 404, 412 y 428) son las de arriba.

Código	HTTP	Significado	Qué hacer
MPBX-RING-GROUP-NAME-TAKEN	409	Otro grupo de timbrado de la empresa tiene este nombre.	Elija otro nombre.
MPBX-RING-GROUP-NO-ANSWER-UNAVAILABLE	400	Retirado (FU-RG-1): el buzón de voz se acepta como destino de sin respuesta; el código ya no se devuelve y queda reservado.	Ninguna.
MPBX-CONFERENCE-ROOM-NAME-TAKEN	409	Otra sala de conferencia de la empresa tiene este nombre (W6-TEL-07).	Elija otro nombre.

Colas, valores predeterminados de buzón de voz, políticas de grabación (W3-API-02)

Se devuelven en /queues, /queue-settings, /voicemail/settings, /recording-settings, /recording-policies y en las rutas de extensiones. Las demás condiciones (validación, 404, 412 y 428) son las de arriba; un destino de grabación que no existe es MPBX-REC-INVALID (grabación).

Código	HTTP	Significado	Qué hacer
MPBX-QUEUE-NAME-TAKEN	409	Otra cola de la empresa tiene este nombre.	Elija otro nombre.
MPBX-EXTENSION-HAS-MAILBOX	409	El buzón de voz de la extensión tiene mensajes o saludos, así que la extensión todavía no se puede eliminar (un buzón vacío se elimina junto con su extensión).	Descargue lo que deba conservarse, elimine el buzón (DELETE /voicemail/mailboxes/{id}) y luego elimine la extensión.

Troncales SIP y DID (W2-API-02)

Se devuelven en /trunks, /trunks/{id}/dids, /trunk-dids y en las vistas de sistema /system/trunk-numbers y /system/trunk-approvals; vea la guía de troncales. Una configuración de troncal que el motor rechaza es MPBX-TRUNK-INVALID (400, errores de troncales).

Código	HTTP	Significado	Qué hacer
MPBX-TRUNK-NAME-TAKEN	409	Otro troncal de la empresa tiene este nombre.	Elija otro nombre.
MPBX-TRUNK-DID-OVERLAP	409	Un DID de la lista se superpone con otra entrada de la lista o con un DID de otro troncal de la empresa (el mensaje nombra el troncal).	Elimine la superposición, o mueva primero el número del otro troncal.
MPBX-TRUNK-DID-TAKEN	409	Un número (un DID, un rango que lo contiene o el número principal de un troncal) pertenece a otra empresa de este sistema: un número pertenece a una sola empresa. El mensaje nunca indica qué empresa, troncal o rango lo tiene; el rechazo queda auditado (trunk.did_refused).	Revise el número. Si es suyo, el administrador del sistema localiza al titular con GET /system/trunk-numbers y lo resuelve.
MPBX-TRUNK-DID-LIMIT	409	La empresa tendría más de 100 000 DID (lo exige la base de datos).	Elimine rangos sin uso, o pida ayuda al administrador del sistema.
MPBX-TRUNK-IN-USE	409	El troncal no se puede eliminar: una regla de salida o un número de emergencia se enruta por él, o las rutas de entrada están limitadas a él (errors los enumera; GET /trunks/{id}/usage los muestra antes).	Cambie primero esos elementos, o elimine con detach_inbound_routes=true para que las rutas de entrada apliquen a cualquier troncal.
MPBX-TRUNK-EMERGENCY-ROUTE	409	Deshabilitar el troncal, o apagar sus llamadas salientes, dejaría un número de emergencia habilitado sin una ruta utilizable (errors lo enumera).	Primero asigne al número de emergencia una ruta en otro troncal, o deshabilítelo.
MPBX-TRUNK-APPROVAL-SYSTEM-ONLY	403	Solo un administrador del sistema que actúa en la empresa aprueba una lista de permitidos de entrada (inbound_acl_approved).	Pida al administrador del sistema; GET /system/trunk-approvals lista las pendientes.
MPBX-TRUNK-HOST-NOT-ALLOWED	403	Una empresa no puede apuntar host, outbound_proxy o registrar a una dirección interna (loopback, privada, de enlace local, NAT de nivel operador, local única, ...), ya sea literal o como un nombre que resuelve a una de ellas (FU-TRK01-12).	Use la dirección o el nombre público del operador; un administrador del sistema puede definir una interna (un operador en un enlace privado).

Horario laboral (W3-TEL-05)

Se devuelven en las rutas de horario laboral (/schedules, /schedule-status, /holiday-sets); vea la guía de horario laboral. Los errores de validación (una zona horaria desconocida, un tramo que se superpone, un campo de día festivo incorrecto, una excepción que termina en el pasado) son el MPBX-INVALID-ARGUMENT (400) genérico, con el campo como puntero JSON en errors[].

Código	HTTP	Significado	Qué hacer
MPBX-SCHEDULE-NAME-TAKEN	409	Otro horario de la empresa tiene este nombre.	Elija otro nombre.
MPBX-SCHEDULE-EXISTS	409	La empresa (o el departamento) ya tiene su horario; hay un horario de empresa y uno por departamento.	Cambie el horario existente (PATCH /schedules/{id}), o cree un horario custom.
MPBX-HOLIDAY-SET-NAME-TAKEN	409	Otro conjunto de días festivos de la empresa tiene este nombre.	Elija otro nombre.
MPBX-HOLIDAY-SET-IN-USE	409	Un horario todavía usa el conjunto de días festivos, así que eliminarlo convertiría en silencio los días festivos en días normales.	Desvincúlelo primero (PATCH /schedules/{id} con no_holiday_set: true).
MPBX-HOLIDAY-SET-FULL	409	El conjunto de días festivos tiene la cantidad máxima permitida (1000).	Elimine los días festivos pasados, o use otro conjunto.
MPBX-CALENDAR-INVALID	400	El archivo subido no es un archivo iCalendar (no tiene BEGIN:VCALENDAR, no es UTF-8), pesa más de 1 MiB o tiene más de 2000 eventos.	Exporte el calendario de nuevo como .ics, o divídalo.

Historial de cambios y reversión (W4-ADM-02)

Se devuelven en POST /api/v1/config-history/{id}/revert (y se muestran como revert.code en GET /api/v1/config-history/{id}); vea la guía del historial de cambios. Un rechazo de la operación que llama la reversión (validación, MPBX-RBAC-FORBIDDEN, MPBX-RBAC-ESCALATION, MPBX-EXTENSION-NUMBER-TAKEN, 412, ...) se devuelve tal cual.

Código	HTTP	Significado	Qué hacer
MPBX-HISTORY-CONFLICT	409	Cambios posteriores tocan los mismos campos del objeto (conflicts[], tipo newer_change, los enumera con sus diferencias), o un cambio posterior de otro objeto menciona el valor que fijó el cambio (tipo dependent_change), o un campo ya no tiene el valor que le dio el cambio y ninguna entrada del historial explica por qué (tipo value_changed, con expected y actual). No se cambió nada.	Revise los cambios enumerados. Revierta primero los más recientes (del más nuevo al más antiguo), o fije el valor a mano.
MPBX-HISTORY-NOT-REVERTIBLE	409	Este tipo de cambio no tiene vuelta atrás: una eliminación (salvo una asignación de rol quitada; la entrada muestra los últimos valores para poder crear el objeto de nuevo), el objeto ya no existe, un campo sin reversor, o la reversión no cambiaría nada.	Cree o cambie el objeto mediante las operaciones normales.
MPBX-HISTORY-SECRET-FIELD	409	El cambio tocó una contraseña, un secreto de dos factores o las credenciales de un dispositivo. El valor anterior no se guarda en ningún lugar, así que no se puede restaurar.	Defina la contraseña de nuevo (restablecimiento de contraseña) o vuelva a registrar el dispositivo o el 2FA.
MPBX-HISTORY-NO-SNAPSHOT	409	La entrada solo registró los nombres de los campos cambiados (el cambio llegó por una vía que todavía no pasa valores), así que no hay nada que restaurar.	Cambie el objeto a mano.
MPBX-HISTORY-ALREADY-REVERTED	409	Un cambio posterior ya revirtió este, y esa reversión sigue vigente.	Revierta la entrada que revirtió si quiere recuperar el cambio.

WebSocket de eventos y marcar con clic (W3-API-01)

Se devuelven en GET /api/v1/events (antes de la actualización, como problem+json; después, en tramas error y códigos de cierre) y en POST /api/v1/calls/click-to-call. Guía: events-ws.md.

Código	HTTP / cierre	Significado	Qué hacer
MPBX-NOT-IMPLEMENTED	501	El contrato de la ruta está publicado, pero su comportamiento no está disponible en esta versión. Hoy ninguna ruta lo responde (POST /api/v1/calls/click-to-call lo hacía hasta MVP-GAP-04; sin motor de llamadas ahora responde 503 MPBX-CALL-ENGINE-UNAVAILABLE, calls.md). La solicitud se autenticó y el cuerpo se validó.	No reintente. Desarrolle con la descripción OpenAPI; la ruta empezará a funcionar en una versión posterior sin cambios en la solicitud ni en la respuesta.
MPBX-EVENTS-WS-UPGRADE-REQUIRED	426	Una solicitud HTTP simple llegó a GET /api/v1/events.	Abra un WebSocket (actualización HTTP/1.1, versión 13).
MPBX-EVENTS-WS-BAD-TOPIC	400 / trama de error	Un nombre de tema no es uno de call, leg, queue, presence, voicemail, config, audit.	Corrija el nombre.
MPBX-EVENTS-WS-BAD-CURSOR	400 / trama de error	El cursor no es un id de evento.	Envíe el cursor de un evento que haya recibido.
MPBX-EVENTS-WS-CURSOR-TOO-LATE	trama de error	Se envió un cursor en un subscribe posterior al primero.	Reconecte con el cursor.
MPBX-EVENTS-WS-BAD-MESSAGE	trama de error, cierre 1008	Una trama del cliente no es JSON de un op conocido, o es binaria. Más de 10 de estas cierran el socket.	Envíe subscribe, unsubscribe, ping (y auth primero si no envió encabezado).
MPBX-EVENTS-WS-NOT-AUTHENTICATED	trama de error, cierre 4401	La primera trama de un socket sin credencial en el encabezado no fue auth.	Envíe primero {"op":"auth","token":...}.
MPBX-EVENTS-WS-AUTH-TIMEOUT	cierre 4401	No llegó una trama auth en 5 s.	Envíela justo después de conectarse.
MPBX-EVENTS-WS-AUTH-FAILED	cierre 4401 / 4403	Se rechazó la credencial de la trama auth; la trama error anterior indica el motivo (MPBX-AUTH-*, MPBX-TENANT-*).	Inicie sesión de nuevo.
MPBX-EVENTS-WS-ALREADY-AUTHENTICATED	trama de error	Una trama auth en un socket ya autenticado.	Ninguna; el socket sigue funcionando.
MPBX-EVENTS-WS-CREDENTIAL-ENDED	cierre 4401	El token de acceso venció, fue revocado, o el usuario fue deshabilitado; lo detecta la revisión periódica (cada 60 s).	Renueve el token y reconecte con el cursor.
MPBX-EVENTS-WS-TOO-MANY	429 / cierre 4429	Demasiadas conexiones de eventos abiertas para este usuario o clave (por defecto 20), para la empresa (5 000) o para toda la instalación (10 000). También es el motivo de cierre de una conexión cerrada para dejar espacio: un socket en espera de autenticación de la red que tiene más sockets en espera, o la conexión más reciente de la empresa que tiene más, cuando otra empresa necesita espacio en una instalación llena. El 429 incluye Retry-After.	Cierre los sockets que no use; comparta un socket por cliente; reconecte con su cursor después del retraso de Retry-After.
MPBX-EVENTS-WS-IDLE	cierre 4408	El cliente no envió nada, ni siquiera un pong, durante 60 s.	Responda a los pings (lo hacen los navegadores) o envíe {"op":"ping"}; reconecte con el cursor.
MPBX-EVENTS-WS-SLOW-CONSUMER	cierre 1013	El cliente no leyó sus tramas con suficiente rapidez; el servidor nunca almacena en búfer sin límite.	Lea continuamente; reconecte con el cursor.

Paquetes de idioma y textos personalizados (W4-L10N-04)

Se devuelven en /api/v1/i18n/packs, /i18n/overrides e /i18n/strings (guía). MPBX-LOCALE-NOT-FOUND (arriba) también lo devuelven las rutas de administración para un idioma que la empresa ni incluye ni subió.

Código	HTTP	Significado	Qué hacer
MPBX-LOCALE-TAG-INVALID	400	La etiqueta de idioma no tiene la forma language[-Script][-REGION][-variant] con letras y dígitos (por ejemplo sv, pt-PT, sr-Latn).	Use una etiqueta BCP 47; las incluidas son en, es-MX, pt-BR, fr, de, it, ru, zh-Hans y ja.
MPBX-LOCALE-RTL-UNSUPPORTED	400	El idioma se escribe de derecha a izquierda (árabe, hebreo, persa, urdu, etc.). Los clientes no tienen diseño de derecha a izquierda (DECISIONS Round 6).	No compatible en la v1.
MPBX-LOCALE-PACK-INVALID	422	El paquete no pasó la validación y no se guardó nada. errors[] enumera hasta 100 problemas con la clave: clave desconocida (no está en el origen en inglés), sintaxis ICU rota, marcadores distintos del inglés, marcado (<b>, <script>), caracteres de control o bidireccionales, un mensaje de más de 2000 caracteres, más de 10 000 claves, un paquete vacío, o falta name para un idioma nuevo.	Corrija las claves enumeradas y suba de nuevo. Ejecute mpbx i18n validate <file> localmente para ver las mismas revisiones.
MPBX-LOCALE-PACK-EXISTS	409	POST /i18n/packs para un idioma que ya tiene un paquete.	Haga GET del paquete para obtener su ETag y reemplácelo con PUT /i18n/packs/{locale}.
MPBX-LOCALE-PACK-LIMIT	409	La empresa ya tiene 30 idiomas subidos.	Elimine un idioma que no use.
MPBX-LOCALE-OVERRIDE-INVALID	422	La clave del texto personalizado no está en el origen en inglés, o el texto tiene sintaxis ICU rota, marcadores distintos del inglés, marcado, caracteres de control, o está vacío o supera 2000 caracteres.	Corrija la clave o el texto; errors[] indica cuál.
MPBX-LOCALE-OVERRIDE-LIMIT	409	El idioma ya tiene 5000 textos personalizados.	Elimine los que no necesite.

Credenciales SIP, perfil SIP e incorporación por QR (W2-API-03)

Se devuelven en /devices/{id}/credentials, /sip-settings, /sip-lock, /unlock, /onboarding-token, las rutas /me/sip-profile y /me/devices, y /onboarding/exchange (guía). Sin los servicios SIP (un error de cableado), estas rutas responden MPBX-API-NOT-CONFIGURED (arriba). Un dispositivo de la extensión de una cuenta que usted no puede administrar es MPBX-ACCOUNT-OUTRANKS o MPBX-ACCOUNT-SYSTEM (arriba).

Código	HTTP	Significado	Qué hacer
MPBX-DEVICE-CHANGED	409	El dispositivo (o su extensión) cambió mientras se emitían credenciales nuevas, por ejemplo fue revocado o editado en el mismo momento. No se cambió nada y ninguna contraseña es válida.	Lea el dispositivo de nuevo y reintente.
MPBX-DEVICE-LIMIT	409	Usted ya tiene la mayor cantidad de dispositivos activos permitida en su propia extensión (10 por defecto).	Revoque un dispositivo que ya no use (POST /me/devices/{id}/revoke), o pida ayuda a un administrador.
MPBX-SIP-SESSION-REQUIRED	403	Se llamó una ruta /me/sip-profile o /me/devices con una clave de API. Sus propios dispositivos SIP se administran solo desde una sesión iniciada.	Inicie sesión (POST /auth/login) y use el token de acceso; los administradores usan las rutas /devices.
MPBX-CDR-SESSION-REQUIRED	403	Se llamó GET /me/calls o /me/calls/{id} con una clave de API. Sus propias llamadas se leen desde una sesión iniciada; el historial de toda la empresa es GET /cdr.	Inicie sesión y use el token de acceso, o use GET /cdr con call_history:read.
MPBX-SIP-NO-EXTENSION	404	Usted no es dueño de ninguna extensión, así que no tiene perfil SIP ni dispositivos.	Pida a un administrador que le asigne una extensión.
MPBX-ONBOARDING-TOKEN-INVALID	401	El código de incorporación es desconocido en esta dirección, venció (10 minutos por defecto), ya se usó, fue reemplazado por un código más nuevo para el mismo dispositivo, o su dispositivo fue revocado o su usuario deshabilitado. Una sola respuesta para todos los casos.	Pida un código QR o enlace nuevo y escanéelo dentro de su vigencia, en la dirección que indica.

Aprovisionamiento de teléfonos de escritorio (W4-DEV-01)

Se devuelven en las rutas /devices/{id}/provisioning y /provisioning/... (guía). Las rutas orientadas al teléfono /prov/... no tienen cuerpo de error: cada rechazo es un 404 vacío (para que nada revele a un atacante qué parte falló), los clientes que exceden el presupuesto reciben 429 MPBX-RATE-LIMITED, y una URL protegida con digest responde 401 con un desafío WWW-Authenticate: Digest.

Código	HTTP	Significado	Qué hacer
MPBX-PROVISIONING-NO-MAC	409	El dispositivo no tiene una dirección MAC utilizable (ninguna, o una que un teléfono no puede tener: todos ceros, una dirección de grupo).	Defina la MAC en el dispositivo (PATCH /devices/{id}) e intente de nuevo.
MPBX-PROVISIONING-EXISTS	409	El dispositivo ya tiene un perfil de aprovisionamiento.	Cámbielo con PATCH, o emita una URL nueva con POST .../regenerate.
MPBX-PROVISIONING-NOT-FOUND	404	El dispositivo no tiene un perfil de aprovisionamiento.	Cree uno con POST /devices/{id}/provisioning.
MPBX-PROVISIONING-LINK-LIMIT	409	El dispositivo ya tiene 5 enlaces de aprovisionamiento firmados sin usar y no vencidos (W6-DEV-01b).	Revóquelos (DELETE /devices/{id}/provisioning/links) o espere a que venzan, y luego emita uno nuevo.

Contactos (MVP-GAP-05)

Código	HTTP	Significado	Qué hacer
MPBX-CONTACT-NUMBER-TAKEN	409	Otro contacto de la misma libreta (la guía telefónica de la empresa, o sus contactos personales) ya tiene este número telefónico; los dígitos de phone identifican a un contacto.	Cambie el contacto existente, o use un número distinto. Una importación CSV actualiza ese contacto en lugar de fallar.
MPBX-CONTACT-LIMIT	409	La libreta superaría su máximo: 200 000 contactos en la guía telefónica de la empresa, 20 000 contactos personales por usuario. Una importación que superaría el límite se revierte por completo.	Elimine los contactos que ya no necesite.
MPBX-CONTACT-IMPORT-BUSY	409	Otra importación de la misma libreta (la guía de la empresa, o los contactos personales del mismo usuario) todavía se está ejecutando, o el servidor ya ejecuta sus dos importaciones de contactos a la vez (todas las empresas juntas; la respuesta incluye Retry-After).	Espere a que termine y reintente.
MPBX-CONTACT-NO-PERSONAL	403	La cuenta no es un usuario de la empresa en la que actúa la solicitud (un administrador del sistema que entró en una empresa), así que no tiene contactos personales allí.	Use la guía telefónica de la empresa, o inicie sesión como usuario de la empresa.

La importación CSV de contactos también responde con los códigos de importación MPBX-IMPORT-MALFORMED (encabezado, comillas o codificación incorrectos, o una carga que se atascó o se cortó), MPBX-IMPORT-TOO-LARGE (más de 100 000 filas o 64 MiB) y MPBX-IMPORT-INVALID (422: filas no válidas y sin skip_invalid).

Notificaciones web push para navegadores (W6-RLY-WEB)

Se devuelven en GET /me/web-push y en PUT / DELETE /me/devices/{id}/web-push (guía). Estas rutas aceptan solo una sesión iniciada (una clave de API da MPBX-SIP-SESSION-REQUIRED, arriba); un dispositivo que no es su propio dispositivo activo es MPBX-NOT-FOUND; más de 10 cambios por minuto son MPBX-RATE-LIMITED (429, Retry-After).

Código	HTTP	Significado	Qué hacer
MPBX-WEB-PUSH-INVALID	400	El cuerpo no es una suscripción de la API Push: el endpoint no es una URL https:// (o supera 1024 caracteres), o keys.p256dh (65 bytes) o keys.auth (16 bytes) faltan o no son base64url de ese tamaño.	Envíe PushSubscription.toJSON() de una suscripción creada con la application_server_key de GET /me/web-push.
MPBX-WEB-PUSH-NOT-BROWSER	409	El dispositivo es un teléfono cuya app móvil registró un token push; una suscripción de navegador lo reemplazaría.	Registre la suscripción para el propio dispositivo del navegador (el dispositivo del softphone web, POST /me/devices).
MPBX-WEB-PUSH-REFUSED	422	El relevo push no entrega a este servicio push del navegador (no es uno de los servicios push públicos conocidos de Chrome, Edge, Firefox y Safari; código de relevo RELAY-WEB-ENDPOINT-REFUSED).	Use un navegador evergreen actual; las llamadas siguen sonando mientras MonoPbx esté abierto.
MPBX-WEB-PUSH-UNAVAILABLE	503	Este servidor no puede enviar web push ahora: no hay relevo push (instalación aislada o no inscrita), no se puede contactar al relevo, el relevo no atiende navegadores, terminó el periodo de gracia de la suscripción, o falló el registro. Entonces GET /me/web-push responde available: false.	Reintente más tarde; un operador revisa el estado del relevo push (docs/guides/push-wake.md).
MPBX-ACT-CODE-INVALID	400	El código de activación manual está mal formado, es desconocido, ya se usó, venció, o está vinculado a otra instalación (código de relevo RELAY-ENROLL-CODE-INVALID).	Revise el código; pida a MonoPbx uno nuevo vinculado a esta instalación (mpbx activate --show-key).
MPBX-ACT-RELAY-UNREACHABLE	503	La activación manual no pudo contactar al relevo push, o la activación manual está desactivada (relay.enroll = false o sin MPBX_RELAY_INSTANCE_KEY).	Permita HTTPS saliente hacia el relevo y reintente; las llamadas no se afectan.
MPBX-ACT-RATE-LIMITED	503	Más de 5 intentos de activación manual (válidos o no) en 15 minutos en esta instalación (W7-SEC-01-C1 ACT-1).	Espere unos minutos e ingrese el código una vez más; revise antes si tiene errores de escritura.
MPBX-OAUTH-INVALID-REQUEST	400	Una solicitud OAuth de un cliente MCP está mal formada (falta un parámetro, verificador o desafío PKCE incorrecto). El endpoint de token responde invalid_request.	Corrija la solicitud del cliente (docs/guides/mcp.md).
MPBX-OAUTH-INVALID-CLIENT	400/401	Cliente MCP desconocido, o la URI de redirección no está registrada para él. El endpoint de autorización responde un 400 simple y nunca redirige.	Registre el cliente de nuevo (POST /oauth/register) con la URI de redirección exacta.
MPBX-OAUTH-INVALID-GRANT	400	El código de autorización o el token de actualización es desconocido, ya se usó, venció, fue revocado, o no coincide con el cliente, la URI de redirección, el verificador o el recurso. Un código ya usado o un token de actualización rotado que se presenta de nuevo revoca la concesión.	Inicie la autorización de nuevo.
MPBX-OAUTH-INVALID-SCOPE	400	Ninguno de los ámbitos solicitados es un permiso que tenga el usuario que inició sesión.	Pida permisos que tenga el usuario, o pida a un administrador un rol.
MPBX-OAUTH-INVALID-TARGET	400	El resource no es el endpoint MCP de este servidor (https://<host>/mcp).	Use el recurso de /.well-known/oauth-protected-resource/mcp.
MPBX-OAUTH-INVALID-REDIRECT-URI	400	Una URI de redirección registrada debe ser https://, o http:// en una dirección loopback, sin fragmento.	Corrija el registro del cliente.
MPBX-OAUTH-TOKEN-INVALID	401	El token de acceso MCP es desconocido, venció, fue revocado, es de otra empresa o es para otro recurso. /mcp responde 401 con un desafío WWW-Authenticate.	Renueve el token o autorice de nuevo.
MPBX-OAUTH-TOO-MANY-CLIENTS	400	La empresa ya tiene 500 clientes MCP registrados.	Un operador elimina los clientes que no se usan (FU-W9-AI-13-2).
MPBX-STORAGE-QUOTA-EXCEEDED	507	La empresa superó el 100 % de su cuota de almacenamiento: se rechazan las nuevas grabaciones de llamadas, los adjuntos de chat y SMS/MMS, los medios de fax y las cargas (guía). Las llamadas nunca se bloquean, el buzón de voz funciona hasta el 110 %, y no se elimina nada.	Libere espacio (elimine grabaciones o archivos antiguos, o acorte la retención) o pida al administrador del sistema que aumente la cuota; la alerta de administración StorageQuotaExceeded ya está activa.
MPBX-DISPOSITION-NOT-PARTICIPANT	403	PUT /me/agent/calls/{id}/disposition: el agente no participó en la llamada (su registro del historial de llamadas no lo nombra, CC-AGENT-006, G-020).	Etiquete solo las llamadas que atendió.
MPBX-DISPOSITION-CALL-PENDING	409	PUT /me/agent/calls/{id}/disposition: la llamada todavía no está en el historial (el registro se escribe cuando termina la llamada).	Reintente después de unos segundos.