Códigos de error#

Cuando la API de Empowerment Center rechaza una petición, responde con un estado HTTP y un cuerpo que dice por qué. Esta página es la referencia de los códigos que puede encontrar un administrador o quien integra otro sistema con ECenter: qué significa cada uno y qué hacer.

El formato de un error#

Los errores van en formato Problem Details (application/problem+json), con un campo code cuando el error tiene un código propio:

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "Ya existe el usuario 'ana'",
  "instance": "/api/security/users",
  "code": "LOGIN_TAKEN"
}

detail es una frase en español para quien lo lee. Puede cambiar entre versiones: un programa no debe decidir por ella.
code es estable: es lo que debe mirar un programa (y lo que mira el frontal para poner el error bajo su campo).
Algunos códigos llevan más campos (la versión actual, los identificadores ocultos, lo que usa un objeto); se dicen en cada uno.
Un error sin code se entiende por su estado (abajo).

Las superficies de portador (la API de consulta, el servidor MCP, la incrustación, SCIM) tienen sus propios formatos y códigos; se resumen al final.

Los estados#

Estado	Qué significa en ECenter
400	Lo enviado no vale: un dato que no cumple su regla, un JSON mal formado. El `detail` dice la causa.
401	No hay sesión (o la credencial no vale, en las superficies de portador).
403	No tiene el privilegio que pide la ruta, o pide algo que no puede ver, o no hay licencia.
404	No existe o ha caducado (un trabajo terminado, tras 30 minutos).
409	Una regla impide hacerlo así: un nombre repetido, algo en uso, algo en marcha.
412	Otro lo cambió desde que usted lo leyó (con `If-Match`). Lleva la versión actual.
413	El fichero o el cuerpo es demasiado grande.
422	Se entiende, pero no se puede hacer con eso (un formato que el documento no admite, un resultado demasiado grande).
429	Demasiado a la vez. Lleva `Retry-After` con los segundos que esperar.
500	Un fallo interno: `INTERNAL_ERROR`.
502	La BD del cliente ha fallado o no ha respondido a tiempo.
503	No se ha podido comprobar algo fuera de ECenter (el proveedor de identidad).

Licencia, sesión y administración#

Código	Estado	Qué significa	Qué hacer
`LICENSE_INVALID`	403	No hay una licencia válida. Lleva `licenseStatus` (`MISSING`, `INVALID`, `OTHER_INSTALLATION`, `EXPIRED`). Solo responden `/api/auth/`, `/api/license`, `/api/me/` y `/api/about`.	Instale una licencia válida en Administración › Licencia (véase Arranque, licencia y acceso).
`LOGIN_DELAYED`	429	Demasiados intentos de entrada fallidos seguidos. Lleva `retryAfter` y la cabecera `Retry-After`.	Esperar esos segundos.
`ADMIN_SYSTEM_REQUIRED`	403	Lo que intenta exige tener Administración del sistema: dar o quitar ese privilegio (un rol que lo incluya, o el privilegio en un rol), o cambiar la contraseña, el estado, el login o el correo de quien lo tiene, o borrarlo.	Que lo haga alguien con Administración del sistema.
`INTERNAL_ERROR`	500	Un fallo interno del servidor. El `detail` es siempre «Error interno del servidor: queda en su registro» y no da más datos a propósito.	Busque en el registro del servidor «Fallo interno en una petición de …» a esa hora, con su traza.

Usuarios y roles#

Código	Estado	Qué significa	Qué hacer
`LOGIN_TAKEN`	409	Ya existe un usuario con ese login.	Elija otro.
`EMAIL_TAKEN`	409	Otro usuario ya tiene ese correo (sin distinguir mayúsculas).	Use otro, o quíteselo al otro usuario.
`INVALID_LOGIN`, `INVALID_EMAIL`, `INVALID_DESCRIPTION`, `INVALID_PASSWORD`	400	El login, el correo, la descripción o la contraseña no cumplen su regla. El `detail` dice cuál.	Corrija ese campo.
`USER_CHANGED`	412	Al cambiar los roles de un usuario con `If-Match`, otro los ha cambiado antes. Lleva la `version` actual.	Vuelva a leerlo y repita el cambio.
`ROLE_CHANGED`	412	Lo mismo con los privilegios de un rol.	Vuelva a leerlo y repita el cambio.
`USER_MANAGED`	409	El usuario lo gestiona el proveedor de identidad (SCIM): ese dato se cambia en el directorio de la organización.	Cámbielo en el directorio.
`ROLE_LINKED`	409	El rol lo da el proveedor de identidad por un grupo enlazado: no se puede asignar ni quitar a mano.	Quite antes el enlace en Usuarios y roles › Aprovisionamiento.
`PRIVILEGE_HAS_UNIVERSES`	409	El privilegio que quiere borrar tiene universos.	Quite antes sus universos.
`TOO_MANY_CREDENTIALS`	409	El titular ya tiene el máximo de credenciales de servicio vigentes (10, `ecenter.security.credentials.max-active-per-holder`).	Revoque alguna antes.
`STALE_VERSION`	409	En el aprovisionamiento, lo que quiere cambiar ha cambiado desde que lo leyó.	Vuelva a cargarlo.
`CONFIRMATION_REQUIRED`, `LOGIN_CHANGE_REQUIRED`	409	En el aprovisionamiento, el cambio necesita que lo confirme (por ejemplo, cambiar el login de un usuario al vincularlo).	Repítalo confirmándolo.

Véase Seguridad.

Lo que el usuario no ve y lo que está en uso#

Código	Estado	Qué significa	Qué hacer
`COLUMNS_HIDDEN`	403	La petición nombra dimensiones o métricas que el usuario no puede ver (seguridad por columnas). Lleva los identificadores que envió en `dimensions` y `metrics`, y `segmentation` si estaban en la segmentación; nunca sus nombres. Queda en la auditoría como Consulta rechazada.	Si debería verlas, dele el privilegio de acceso de esas columnas. Si no, es lo esperado.
`HIDDEN_COLUMNS_NOT_EDITABLE`	403	Quiere guardar un documento (o un marcador de página) que usa columnas que usted no ve: para usted es de solo lectura.	Que lo guarde alguien que vea todo lo que usa.
`IN_USE`	409	Quiere eliminar algo que otros usan (un libro o documentos de un libro, una lista, unos datos externos, una capa, una plantilla). Lleva `subject`, `usages` (lo que usted puede abrir, por nombre) y `hidden` (cuántos más no puede abrir).	Revise lo que se rompería. Para eliminarlo igualmente, repita con `confirmed=true`; para saberlo sin eliminar, `preview=true`. La baja queda en la auditoría con lo que la usaba.

Véase Seguridad.

Metadata#

Código	Estado	Qué significa	Qué hacer
`NAME_TAKEN`	409	El nombre ya lo tiene otro elemento de su clase (una conexión, una agrupación…).	Use otro nombre.
`METADATA_IMPACT`	409	El cambio afecta a documentos, listas o publicaciones, y hay que confirmarlo.	Revise el informe de impacto y repita con `confirmed=true`.
`METADATA_IN_USE`	409	Una regla impide el cambio (algo lo usa de forma que no se puede romper). No se puede confirmar.	Quite antes lo que lo usa.
`METADATA_CHANGED`	412	Otro guardó el elemento después de que usted lo leyera. Lleva la versión actual.	Vuelva a leerlo y repita el cambio.
`DIAGRAM_CHANGED`	412	Lo mismo con la disposición del diagrama de relaciones.	Vuelva a leerlo.
`IMPORT_IN_PROGRESS`	409	Ya hay otra importación o restauración del metadata en curso en esa conexión, en esta instancia o en otra. Dice quién la lanzó.	Espere a que termine.
`PACKAGE_TOO_LARGE`	413	El paquete de metadata pasa de sus límites (64 MB descomprimido, 5 000 ficheros, 16 MB por fichero).	Revise el paquete; los límites están en `ecenter.metadata.exchange.*`.

Véase Metadata.

Trabajos#

Código	Estado	Qué significa	Qué hacer
`TOO_MANY_JOBS`	429	El usuario ya tiene 100 trabajos de esa clase esperando en la cola (`ecenter.jobs.max-queued-per-user`). Lleva `limit` y `Retry-After: 10`.	Esperar o cancelar alguno desde el panel Actividad (véase Trabajos y colas).
`JOB_FAILED`	500	El trabajo de una exportación de una página del portal o del intercambio del metadata ha fallado. El `detail` dice el error.	Mire el error; si es interno, el registro.
`JOB_CANCELED`	409	Ese trabajo se ha cancelado.	Vuelva a pedirlo si hace falta.

Algunos trabajos fallidos llevan un código en su error (errorCode del trabajo), que el frontal usa para decir qué hacer:

Código	Qué significa
`HEAVY_CUBE`	La BD estima más filas de las que se calculan sin preguntar (`ecenter.cube.warn-rows`, 100 000): el usuario tiene que confirmarlo.
`CONNECTION_UNAVAILABLE`	La conexión está inactiva.
`CLIENT_DATABASE_UNAVAILABLE`	La BD del cliente ha fallado o no ha respondido.
`GROUPING_INVALID`	La agrupación no se puede cargar en su tabla de trabajo tal como está.
`QUERY_INVALID`, `QUERY_NOT_ALLOWED`	Una consulta ad hoc no es válida o el usuario no puede hacerla.
`REQUIRED_FILTER`, `NOTHING_TO_EXPORT`, `TOO_HEAVY`	Al exportar una página del portal: falta elegir un valor en un filtro obligatorio, la página no tiene nada que exportar, o no cabe en Excel (422).

Consola de operación#

Código	Estado	Qué significa
`UNKNOWN_SERIES`	400	Se ha pedido una serie de actividad que no existe o que la instalación no ofrece. Lleva `series`.
`INVALID_PERIOD`	400	El periodo o el tramo de la actividad no vale (no existe, más de un año, una fecha que no es ISO 8601…).
`LAYOUT_CHANGED`	412	Otra sesión ha cambiado la disposición de la pestaña Actividad. Lleva `layout`, la de ahora.
`INVALID_LAYOUT`	400	La disposición enviada no vale (más de 40 gadgets, un identificador repetido, unas opciones de más de 2 KB…).

Suscripciones y alertas de datos#

Código	Estado	Qué significa
`SUBSCRIPTION_INVALID`	400	La suscripción no es válida; el `detail` dice qué.
`DATA_ALERT_INVALID`, `DATA_ALERT_TRIGGER_INVALID`	400	La alerta de datos o su disparador no son válidos.
`FORMAT_UNAVAILABLE`	422	El documento no admite ese formato (un formulario no tiene fichero; un gráfico o un mapa solo dan sus datos en Excel; el PDF necesita el navegador sin interfaz).
`NOT_WATCHABLE`	422	El documento no tiene valores que vigilar.
`RESTRICTION_NOT_APPLICABLE`	400	Un documento publicado congelado no admite una segmentación: lleva los datos de la publicación.
`RECIPIENTS_NOT_ALLOWED`	403	Avisar a otros usuarios exige el privilegio de suscribir a otros.
`SUBSCRIPTION_LIMIT`, `DATA_ALERT_LIMIT`	409	El responsable ya tiene el máximo (50 de cada, `ecenter.distribution.max-per-owner` y `alerts.max-per-owner`).
`MAIL_UNAVAILABLE`	409	No hay servidor de correo configurado (véase Correo y avisos).
`NO_EMAIL`	409	El usuario no tiene correo.
`RUN_IN_PROGRESS`, `TEST_IN_PROGRESS`, `EVALUATION_IN_PROGRESS`	409	Ya hay un envío, una prueba o una evaluación en marcha.

Superficies de portador#

La API de consulta, el servidor MCP, la incrustación, el intercambio del metadata sin sesión y SCIM se usan con una credencial de servicio (o un token), no con una sesión. Sus códigos se explican con detalle en Integraciones; estos son los que más ve un administrador:

Código	Estado	Qué significa
`CREDENTIAL_REQUIRED`	401	Falta la credencial.
`INVALID_CREDENTIAL`	401	La credencial no existe, ha caducado, se ha revocado o su titular ya no puede usarla.
`NOT_ALLOWED`	403	El titular no tiene el privilegio de esa superficie, o la credencial no incluye esa conexión.
`INSUFFICIENT_SCOPE`	403	Al token de OAuth del MCP le falta el ámbito: hay que volver a autorizar el cliente.
`IDENTITY_PROVIDER_UNAVAILABLE`	503	No se ha podido comprobar un token de OAuth porque su emisor no responde.
`LICENSE_INVALID`	403	No hay licencia válida (sin excepciones en estas superficies).
`API_DISABLED`, `MCP_DISABLED`	404	La API de consulta o el MCP están apagados (`ecenter.api.enabled`, `ECENTER_MCP_ENABLED`).
`TOO_MANY_RUNNING`	429	Demasiadas consultas en curso del titular o demasiados trabajos en cola. Con `Retry-After`.
`RATE_LIMITED`	429	Demasiadas peticiones por minuto de esa credencial. Con `Retry-After`.
`HEAVY_QUERY`	409	Consulta pesada: hay que repetirla confirmándolo.
`TOO_HEAVY`	422	El resultado pasa de los límites y no se calcula ni confirmándolo.
`RESULT_NOT_FOUND`	404	El resultado no está en esta instancia (caducó, se descartó o el proxy no tiene afinidad).
`CLIENT_DATABASE`	502	La BD del cliente ha fallado.
`QUERY_FAILED`	500	Un fallo interno de la consulta; el detalle está en el registro.
`EMBED_TOKEN_INVALID`, `EMBED_TOKEN_EXPIRED`, `EMBED_TOKEN_REPLAYED`, `EMBED_ORIGIN_NOT_ALLOWED`, `EMBED_APP_DISABLED`…	4xx	Errores de la incrustación: el token no vale, ha caducado, se ha usado ya, la página anfitriona no es de un origen permitido, la aplicación está desactivada…