# Códigos de error: Acceso: login, sesión y entidad

> Login con Zauru, cambio de entidad, alta y edición de usuarios de una entidad.

**Cómo se detecta (toda la familia):** Hoy un 4xx con código no deja línea en Render (Nest no registra las excepciones HTTP): el `code` está en la respuesta (DevTools → Red) y Render solo muestra la petición con su status (`type: request`, filtro por `path` y `statusCode`). Los 503 de Zauru sí dejan línea de la sesión de Zauru.

**Qué hacer (toda la familia):** Casi todos son datos de la persona o de la entidad (usuario sin acceso, rol de otra entidad, correo duplicado): se corrigen en la pantalla de usuarios o en Zauru. Los 503 son de Zauru: reintentar.

Lo que un código no dice lo hereda de la familia.

## `AGENT_ACCOUNT_INTERACTIVE_LOGIN_FORBIDDEN`

- **Tipo:** HTTP · **HTTP:** 403 · **Estado:** vigente
- **Qué significa:** Se intentó entrar a la pantalla con la cuenta de la IA de Boost (`users.kind = agent`): esa cuenta solo inicia sesión como `cli` o `agent`, nunca en el navegador.
- **Causa típica:** Alguien usó las credenciales de la cuenta de IA en el login web.
- **Qué hacer:** Entrar con la cuenta propia de la persona. La cuenta de IA se usa desde la CLI (`yarn -s boost …`).

## `auth_sessions_unavailable`

- **Tipo:** HTTP · **HTTP:** 503 · **Estado:** vigente
- **Qué significa:** No se pudo abrir o revocar la sesión en `auth_sessions` (la base falló): falla cerrado; en el login no se entra.

## `automation_user_login_forbidden`

- **Tipo:** HTTP · **HTTP:** 403 · **Estado:** vigente
- **Qué significa:** Se intentó iniciar sesión con un usuario que es una identidad de automatización (el usuario API con que corren los workflows). Ese usuario no puede entrar a la pantalla.
- **Causa típica:** Alguien usó las credenciales del usuario de servicio de la entidad para entrar a Boost.
- **Qué hacer:** Entrar con el usuario propio de la persona. El usuario de servicio solo lo usan los workflows.

## `crm_entity_access_denied`

- **Tipo:** HTTP · **HTTP:** 403 · **Estado:** vigente
- **Qué significa:** El usuario no tiene acceso al CRM en la entidad pedida.

## `crm_entity_required`

- **Tipo:** HTTP · **HTTP:** 409 · **Estado:** vigente
- **Qué significa:** Para cambiar de entidad hace falta una entidad del CRM activa.

## `duplicate_user_email`

- **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente
- **Qué significa:** El mismo correo viene más de una vez en la lista de usuarios a crear.

## `duplicate_zauru_employee_id`

- **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente
- **Qué significa:** El mismo empleado de Zauru viene más de una vez en la lista de usuarios a crear.

## `employee_belongs_to_other_entity`

- **Tipo:** HTTP · **HTTP:** 409 · **Estado:** vigente
- **Qué significa:** El empleado de Zauru ya existe en otra entidad de Boost; no se puede crear de nuevo en esta.

## `entity_user_name_required`

- **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente
- **Qué significa:** Se pidió dejar vacío el nombre de una persona al corregirla.

## `entity_user_not_found`

- **Tipo:** HTTP · **HTTP:** 404 · **Estado:** vigente
- **Qué significa:** La persona que se quiso corregir no es un empleado de la entidad activa.

## `entity_user_update_empty`

- **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente
- **Qué significa:** Se pidió corregir a una persona (Roles y permisos > Personas) sin mandar ni nombre ni correo.

## `entity_user_without_login`

- **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente
- **Qué significa:** Se quiso corregir el correo de una persona que no tiene usuario para iniciar sesión (empleado sin `user_id`).

## `PLATFORM_ENTITY_ACCESS_REQUIRED`

- **Tipo:** HTTP · **HTTP:** 403 · **Estado:** vigente
- **Qué significa:** El perfil demo solo entra a las entidades con acceso concedido.

## `PLATFORM_ONLY`

- **Tipo:** HTTP · **HTTP:** 403 · **Estado:** vigente
- **Qué significa:** La operación es solo para usuarios de plataforma (p. ej. consultar a otros usuarios o entidades).

## `platform_user_email_locked`

- **Tipo:** HTTP · **HTTP:** 403 · **Estado:** vigente
- **Qué significa:** Se quiso cambiar desde Personas el correo de otra cuenta de plataforma (superadmin, soporte o demo).

## `PRINCIPAL_ROLE_LOCKED`

- **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente
- **Qué significa:** El rol de la identidad API (usuario de workflows) y el de un superadmin no se dan ni se cambian desde la pantalla de usuarios.

## `role_not_found`

- **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente
- **Qué significa:** El rol elegido no existe.

## `role_outside_entity`

- **Tipo:** HTTP · **HTTP:** 403 · **Estado:** vigente
- **Qué significa:** El rol elegido es de otra entidad.

## `service_identity_api_key_invalid`

- **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente
- **Qué significa:** Zauru rechazó la apikey de la identidad de servicio: no es la de ese usuario o no tiene acceso a la entidad.

## `service_identity_api_key_required`

- **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente
- **Qué significa:** Una identidad de servicio (usuario de workflows) necesita su apikey de Zauru; sin ella los workflows de la entidad no pueden escribir en Zauru.

## `SERVICE_USER_ALREADY_EXISTS`

- **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente
- **Qué significa:** La entidad ya tiene su identidad API (usuario de servicio): solo puede haber una por entidad.

## `service_user_email_locked`

- **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente
- **Qué significa:** Se quiso cambiar desde Personas el correo de la identidad de servicio (api@) o de la cuenta de IA; sus credenciales se administran aparte.

## `super_admin_not_assignable_here`

- **Tipo:** HTTP · **HTTP:** 403 · **Estado:** vigente
- **Qué significa:** El rol `super_admin` no se puede asignar desde la pantalla de usuarios de la entidad.

## `supervisor_not_found`

- **Tipo:** HTTP · **HTTP:** 400, 409 · **Estado:** vigente
- **Qué significa:** El supervisor indicado no se encontró al armar la jerarquía supervisor-vendedor.

## `supervisor_ref_on_non_seller`

- **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente
- **Qué significa:** Se le puso supervisor a alguien cuyo rol no es de vendedor; la jerarquía solo aplica a vendedores.

## `user_email_taken`

- **Tipo:** HTTP · **HTTP:** 409 · **Estado:** vigente
- **Qué significa:** El correo nuevo ya es de otro usuario de Boost: `users.email` es único y global.

## `user_email_zauru_id_mismatch`

- **Tipo:** HTTP · **HTTP:** 409 · **Estado:** vigente
- **Qué significa:** El correo ya pertenece a otro usuario con un `zauru_id` distinto al del pedido.

## `user_is_super_admin`

- **Tipo:** HTTP · **HTTP:** 409 · **Estado:** vigente
- **Qué significa:** Se pidió darle rol de entidad a un super admin; no lo necesita (ya tiene acceso a todas). Hay que quitarlo de la lista.

## `zauru_entity_switch_incomplete`

- **Tipo:** HTTP · **HTTP:** 503 · **Estado:** vigente
- **Qué significa:** Zauru hizo el cambio de entidad pero la sesión de la entidad destino todavía no está lista (503): reintentar.

## `zauru_unavailable`

- **Tipo:** detalle, HTTP · **HTTP:** 503 · **Estado:** vigente
- **Qué significa:** Zauru respondió con error 5xx durante el login: está caído o con problemas (503).