Roles, permisos y autorización

Códigos de error · 65 códigos · catálogo del 2026-10-21

Roles, reglas de alcance, techo de permisos al asignar, explicación de accesos (authz-explain) y auditoría de decisiones (authz_decisions).

Para toda la familia

Lo que un código no dice lo hereda de aquí.

Cómo se detecta: El code viaja en la respuesta. Las negaciones de principales de servicio quedan en authz_decisions (allowed = 0, con su reason_code). El techo de permisos escribe una línea JSON con reasonCode en shadow.
Qué hacer: Revisar el rol y sus permisos en la pantalla de roles (o yarn -s boost authz …). Un *_AUDIT_UNAVAILABLE significa que no se pudo escribir la auditoría y por eso no se hizo nada: reintentar.

65 códigos

Códigos

`AUDIT_INVALID_DECISION`

interno

La decisión de autorización que se quiso auditar trae un campo inválido (entidad, principal, superficie, recurso). Es un bug de quien la registra: no se hizo el efecto.

`AUDIT_UNAVAILABLE`

interno

No se pudo escribir la decisión de autorización en la auditoría.

`AUTHZ_VERSION_BUMP_UNCONFIRMED`

interno

La base no confirmó la versión nueva.

`AUTHZ_VERSION_SUBJECT_INVALID`

interno

El tipo de sujeto no está en la lista permitida.

`AUTHZ_VERSION_UNREADABLE`

interno

La versión guardada no se puede leer.

`ENTITY_ID_REQUIRED`

HTTPHTTP 400

La sesión no tiene entidad activa: mande ?entity_id=N

`FORBIDDEN`

HTTPHTTP 403

Solo plataforma puede consultar otras entidades

`GRANT_BY_AUTOMATION`

detalleHTTPHTTP 403

Una automatización no puede administrar accesos

`GRANT_EXCEEDS_ACTOR`

detalleHTTPHTTP 403

No puedes conceder permisos que tú no tienes

`GRANT_NOT_ASSIGNABLE`

detalleHTTPHTTP 403

Tu tipo de usuario no puede asignar uno o más de estos permisos

No puedes crear ni asignar un rol que ve más registros que tú: un rol que ve toda la entidad o los clientes de una regla (el promotor) solo lo crea o lo asigna plataforma o quien ya ve toda la entidad.

`INVALID_ENTITY_ID`

HTTPHTTP 400

entity_id debe ser un entero positivo

`INVALID_ID`

HTTPHTTP 400

Un id de la ruta no es un entero positivo escrito tal cual.

`PLATFORM_ACCESS_ALREADY_LIVE`

HTTPHTTP 400

Ya hay un acceso vivo para ese usuario, entidad y perfil. Revócalo primero.

`PLATFORM_ACCESS_BY_AUTOMATION`

HTTPHTTP 403

Una automatización no administra accesos de plataforma.

`PLATFORM_ACCESS_ENTITY_NOT_FOUND`

HTTPHTTP 400

La entidad del acceso de plataforma no existe o no es un entero positivo.

`PLATFORM_ACCESS_EXPIRES_INVALID`

HTTPHTTP 400

expires_at del acceso de plataforma no es una fecha ISO 8601 futura.

`PLATFORM_ACCESS_FIELD_CLASSES_INVALID`

HTTPHTTP 400

Las clases de campos (field_classes) del acceso de plataforma no son válidas (vacías, muy largas o con caracteres no permitidos).

`PLATFORM_ACCESS_NOT_FOUND`

HTTPHTTP 404

El acceso de plataforma no existe (o no se pudo releer después de crearlo).

`PLATFORM_ACCESS_PROFILE_INVALID`

HTTPHTTP 400

profile tiene que ser support o demo.

`PLATFORM_ACCESS_PROFILE_MISMATCH`

HTTPHTTP 400

El perfil pedido no es el platform_profile del usuario.

`PLATFORM_ACCESS_REASON_INVALID`

HTTPHTTP 400

El motivo del acceso de plataforma es muy corto o muy largo.

`PLATFORM_ACCESS_SELF_GRANT`

HTTPHTTP 400

Nadie se concede acceso a sí mismo.

`PLATFORM_ACCESS_SERVICE_USER`

HTTPHTTP 400

Un usuario de servicio no tiene acceso de plataforma.

`PLATFORM_ACCESS_USER_ID_REQUIRED`

HTTPHTTP 400

user_id tiene que ser un entero positivo.

`PLATFORM_ACCESS_USER_INACTIVE`

HTTPHTTP 400

El usuario está inactivo.

`PLATFORM_ACCESS_USER_NOT_FOUND`

HTTPHTTP 400

El usuario no existe.

`ROLE_NOT_FOUND`

HTTPHTTP 404

El rol consultado no existe (explicación de accesos).

`ROLE_SCOPE_ENTITY_PLATFORM_ONLY`

HTTPHTTP 403

Solo plataforma puede crear un rol que ve toda la entidad (plantilla admin). Un admin de entidad asigna el rol admin que ya existe; no crea otro.

`ROLE_SCOPE_PROFILE_INVALID`

HTTPHTTP 400

scope_profile del rol no es uno de los perfiles de alcance permitidos.

`ROLE_SCOPE_PROFILE_SOURCE_INVALID`

HTTPHTTP 400

scope_profile_source del rol no es uno de los valores permitidos.

`ROLE_SCOPE_PROFILE_SOURCE_REQUIRED`

HTTPHTTP 400

scope_profile y scope_profile_source van juntos o ninguno

`ROLE_SCOPE_RULE_EMPLOYEE_UNKNOWN`

HTTPHTTP 400

La regla de alcance del rol nombra un empleado que no existe en la entidad.

`ROLE_SCOPE_RULE_ENTITY_REQUIRED`

HTTPHTTP 400

Un rol con scope_rule tiene que pertenecer a una entidad

`ROLE_SCOPE_RULE_INVALID`

internoHTTPHTTP 400

La regla de alcance (scope_rule_json) del rol no tiene la forma esperada.

`ROLE_SCOPE_RULE_MISMATCH`

HTTPHTTP 400

scope_rule_json es obligatorio con scope_profile 'criteria' y no se admite con otro perfil

`ROLE_SCOPE_RULE_NOT_CRITERIA`

HTTPHTTP 400

scope_rule solo se admite en un rol con scope_profile 'criteria'

`ROLE_SCOPE_RULE_REQUIRED`

HTTPHTTP 400

Un rol promotor necesita scope_rule

`ROLE_SCOPE_RULE_TOO_LARGE`

internoHTTPHTTP 400

La regla de alcance del rol supera el tamaño máximo permitido.

`ROLE_SCOPE_RULE_TYPE_NOT_AVAILABLE`

interno

La regla de alcance usa un tipo de criterio que todavía no existe.

`ROLE_TEMPLATE_KEY_INVALID`

HTTPHTTP 400

template_key no es una de las plantillas de rol conocidas.

`ROLE_TEMPLATE_UNKNOWN`

HTTPHTTP 400

template_key no es una de las plantillas con las que se puede crear un rol.

`SERVICE_ACTION_NOT_ALLOWED`

interno

La política del principal de servicio no permite esa acción.

`SERVICE_CROSS_ENTITY`

interno

El principal de servicio quiso actuar sobre un recurso de otra entidad.

`SERVICE_ENTITY_REQUIRED`

interno

El principal de servicio se resuelve por entidad y no se dio una válida.

`SERVICE_IS_PLATFORM_SCOPED`

interno

El principal de servicio es de plataforma y se pidió con entidad.

`SERVICE_KIND_WITHOUT_POLICY`

interno

Ese tipo de servicio no tiene política en código.

`SERVICE_PRINCIPAL_ALTA_ACTOR_INACTIVE`

interno

El usuario que autoriza el alta de principales está inactivo.

`SERVICE_PRINCIPAL_ALTA_ACTOR_INVALID`

interno

El actorUserId del alta de principales no es un entero positivo.

`SERVICE_PRINCIPAL_ALTA_ACTOR_NOT_FOUND`

interno

El usuario que autoriza el alta de principales no existe.

`SERVICE_PRINCIPAL_ALTA_ACTOR_NOT_HUMAN`

interno

Quien autoriza el alta de principales no es una persona (users.kind es service o agent): una automatización o la IA no dan de alta principales (regla heredada del script alta-principales-de-servicio.js).

`SERVICE_PRINCIPAL_ALTA_ENTITY_INVALID`

interno

El entityId del alta de principales no es un entero positivo.

`SERVICE_PRINCIPAL_ALTA_ENTITY_NOT_FOUND`

interno

La entidad para la que se piden principales de servicio no existe en entities.

`SERVICE_PRINCIPAL_ALTA_ID_UNREADABLE`

interno

Tras insertar un principal no se pudo leer su id: el alta se aborta y la transacción se revierte. Error de datos, no de uso.

`SERVICE_PRINCIPAL_ALTA_TX_REQUIRED`

interno

ensureEntityPrincipals se llamó sin una transacción activa: el alta de un principal y su decisión de auditoría van juntas o no van. Error de programación, no de uso.

Qué hacer: Llamarlo con el EntityManager de una transacción abierta (el alta de entidad y completeAuthz ya lo hacen).

`SERVICE_PRINCIPAL_ALTA_WITHOUT_AUDIT`

interno

ensureEntityPrincipals no tiene AuthzAuditService inyectado: sin auditoría no se da de alta ningún principal.

Qué hacer: Revisar el módulo que arma ServicePrincipalService; en la app real siempre viene.

Causa típica: Falta dar de alta el principal (p. ej. channel_onboarding, media_refresh) en la entidad.
Qué hacer: Darlo de alta con las herramientas de scripts/authz/ (plataforma).

Texto generado desde el catálogo de errores de BoostAPI. Para corregirlo, se cambia allá y se sincroniza: verMantener esta documentación. También enMarkdown.