# Códigos de error: Roles, permisos y autorización > Roles, reglas de alcance, techo de permisos al asignar, explicación de accesos (`authz-explain`) y auditoría de decisiones (`authz_decisions`). **Cómo se detecta (toda la familia):** 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 (toda la familia):** 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. Lo que un código no dice lo hereda de la familia. ## `AUDIT_INVALID_DECISION` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** 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` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** No se pudo escribir la decisión de autorización en la auditoría. ## `AUTHZ_VERSION_BUMP_UNCONFIRMED` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** La base no confirmó la versión nueva. ## `AUTHZ_VERSION_SUBJECT_INVALID` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** El tipo de sujeto no está en la lista permitida. ## `AUTHZ_VERSION_UNREADABLE` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** La versión guardada no se puede leer. ## `ENTITY_ID_REQUIRED` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** La sesión no tiene entidad activa: mande ?entity_id=N ## `FORBIDDEN` - **Tipo:** HTTP · **HTTP:** 403 · **Estado:** vigente - **Qué significa:** Solo plataforma puede consultar otras entidades ## `GRANT_BY_AUTOMATION` - **Tipo:** detalle, HTTP · **HTTP:** 403 · **Estado:** vigente - **Qué significa:** Una automatización no puede administrar accesos ## `GRANT_EXCEEDS_ACTOR` - **Tipo:** detalle, HTTP · **HTTP:** 403 · **Estado:** vigente - **Qué significa:** No puedes conceder permisos que tú no tienes ## `GRANT_NOT_ASSIGNABLE` - **Tipo:** detalle, HTTP · **HTTP:** 403 · **Estado:** vigente - **Qué significa:** Tu tipo de usuario no puede asignar uno o más de estos permisos ## `GRANT_SCOPE_EXCEEDS_ACTOR` - **Tipo:** detalle, HTTP · **HTTP:** 403 · **Estado:** vigente - **Qué significa:** 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` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** entity_id debe ser un entero positivo ## `INVALID_ID` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** Un id de la ruta no es un entero positivo escrito tal cual. ## `PLATFORM_ACCESS_ALREADY_LIVE` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** Ya hay un acceso vivo para ese usuario, entidad y perfil. Revócalo primero. ## `PLATFORM_ACCESS_BY_AUTOMATION` - **Tipo:** HTTP · **HTTP:** 403 · **Estado:** vigente - **Qué significa:** Una automatización no administra accesos de plataforma. ## `PLATFORM_ACCESS_ENTITY_NOT_FOUND` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** La entidad del acceso de plataforma no existe o no es un entero positivo. ## `PLATFORM_ACCESS_EXPIRES_INVALID` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** `expires_at` del acceso de plataforma no es una fecha ISO 8601 futura. ## `PLATFORM_ACCESS_FIELD_CLASSES_INVALID` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** 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` - **Tipo:** HTTP · **HTTP:** 404 · **Estado:** vigente - **Qué significa:** El acceso de plataforma no existe (o no se pudo releer después de crearlo). ## `PLATFORM_ACCESS_PROFILE_INVALID` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** `profile` tiene que ser support o demo. ## `PLATFORM_ACCESS_PROFILE_MISMATCH` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** El perfil pedido no es el `platform_profile` del usuario. ## `PLATFORM_ACCESS_REASON_INVALID` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** El motivo del acceso de plataforma es muy corto o muy largo. ## `PLATFORM_ACCESS_SELF_GRANT` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** Nadie se concede acceso a sí mismo. ## `PLATFORM_ACCESS_SERVICE_USER` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** Un usuario de servicio no tiene acceso de plataforma. ## `PLATFORM_ACCESS_USER_ID_REQUIRED` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** `user_id` tiene que ser un entero positivo. ## `PLATFORM_ACCESS_USER_INACTIVE` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** El usuario está inactivo. ## `PLATFORM_ACCESS_USER_NOT_FOUND` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** El usuario no existe. ## `ROLE_NOT_FOUND` - **Tipo:** HTTP · **HTTP:** 404 · **Estado:** vigente - **Qué significa:** El rol consultado no existe (explicación de accesos). ## `ROLE_SCOPE_ENTITY_PLATFORM_ONLY` - **Tipo:** HTTP · **HTTP:** 403 · **Estado:** vigente - **Qué significa:** 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` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** `scope_profile` del rol no es uno de los perfiles de alcance permitidos. ## `ROLE_SCOPE_PROFILE_SOURCE_INVALID` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** `scope_profile_source` del rol no es uno de los valores permitidos. ## `ROLE_SCOPE_PROFILE_SOURCE_REQUIRED` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** scope_profile y scope_profile_source van juntos o ninguno ## `ROLE_SCOPE_RULE_EMPLOYEE_UNKNOWN` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** La regla de alcance del rol nombra un empleado que no existe en la entidad. ## `ROLE_SCOPE_RULE_ENTITY_REQUIRED` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** Un rol con scope_rule tiene que pertenecer a una entidad ## `ROLE_SCOPE_RULE_INVALID` - **Tipo:** interno, HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** La regla de alcance (`scope_rule_json`) del rol no tiene la forma esperada. ## `ROLE_SCOPE_RULE_MISMATCH` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** scope_rule_json es obligatorio con scope_profile 'criteria' y no se admite con otro perfil ## `ROLE_SCOPE_RULE_NOT_CRITERIA` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** scope_rule solo se admite en un rol con scope_profile 'criteria' ## `ROLE_SCOPE_RULE_REQUIRED` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** Un rol promotor necesita scope_rule ## `ROLE_SCOPE_RULE_TOO_LARGE` - **Tipo:** interno, HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** La regla de alcance del rol supera el tamaño máximo permitido. ## `ROLE_SCOPE_RULE_TYPE_NOT_AVAILABLE` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** La regla de alcance usa un tipo de criterio que todavía no existe. ## `ROLE_TEMPLATE_KEY_INVALID` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** `template_key` no es una de las plantillas de rol conocidas. ## `ROLE_TEMPLATE_UNKNOWN` - **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente - **Qué significa:** `template_key` no es una de las plantillas con las que se puede crear un rol. ## `SERVICE_ACTION_NOT_ALLOWED` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** La política del principal de servicio no permite esa acción. ## `SERVICE_CROSS_ENTITY` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** El principal de servicio quiso actuar sobre un recurso de otra entidad. ## `SERVICE_ENTITY_REQUIRED` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** El principal de servicio se resuelve por entidad y no se dio una válida. ## `SERVICE_IS_PLATFORM_SCOPED` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** El principal de servicio es de plataforma y se pidió con entidad. ## `SERVICE_KIND_WITHOUT_POLICY` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** Ese tipo de servicio no tiene política en código. ## `SERVICE_PRINCIPAL_ALTA_ACTOR_INACTIVE` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** El usuario que autoriza el alta de principales está inactivo. ## `SERVICE_PRINCIPAL_ALTA_ACTOR_INVALID` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** El `actorUserId` del alta de principales no es un entero positivo. ## `SERVICE_PRINCIPAL_ALTA_ACTOR_NOT_FOUND` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** El usuario que autoriza el alta de principales no existe. ## `SERVICE_PRINCIPAL_ALTA_ACTOR_NOT_HUMAN` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** 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` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** El `entityId` del alta de principales no es un entero positivo. ## `SERVICE_PRINCIPAL_ALTA_ENTITY_NOT_FOUND` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** La entidad para la que se piden principales de servicio no existe en `entities`. ## `SERVICE_PRINCIPAL_ALTA_ID_UNREADABLE` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** 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` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** `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` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** `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. ## `SERVICE_PRINCIPAL_INACTIVE` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** El principal de servicio existe pero no está activo. ## `SERVICE_PRINCIPAL_LOOKUP_FAILED` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** No se pudo consultar el principal de servicio. ## `SERVICE_PRINCIPAL_NOT_FOUND` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** No existe un principal de servicio de ese tipo para esa entidad o alcance. - **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). ## `SERVICE_PRINCIPAL_NOT_ISSUED` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** Ese principal no lo emitió este servicio: se obtiene con resolve. ## `SERVICE_PRINCIPAL_ROW_MISMATCH` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** La fila del principal no corresponde a lo que se pidió. ## `SERVICE_PRINCIPALS_DISABLED` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** Los principales de servicio están apagados. ## `SERVICE_RESOURCE_ENTITY_REQUIRED` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** El recurso tiene que decir de qué entidad es. ## `SERVICE_RESOURCE_TYPE_NOT_ALLOWED` - **Tipo:** interno · **HTTP:** — · **Estado:** vigente - **Qué significa:** La política del principal de servicio no incluye ese tipo de recurso. ## `USER_NOT_FOUND` - **Tipo:** HTTP · **HTTP:** 404 · **Estado:** vigente - **Qué significa:** El usuario consultado no existe (explicación de accesos).