Códigos de error

Además de los códigos de estado HTTP estándar, varias operaciones de la API de RealityConnect devuelven un código error legible por máquina en el cuerpo de la respuesta para aclarar por qué se rechazó una solicitud. Esta página cataloga cada código con nombre por endpoint, qué lo activa y cómo gestionarlo.

---

Forma de la respuesta

Las operaciones que devuelven un código con nombre usan esta forma, con campos adicionales específicos del contexto indicados en cada endpoint más abajo:

{
  "statusCode": 409,
  "error": "NodeHasDerivatives",
  "message": "..."
}

message es opcional y, cuando está presente, da un detalle legible por humanos. Basa tu manejo en error, no en message.

Jerarquía de nodos de datos

Mover un nodo

PATCH /v1/nodes/{nodeId}/move/{newParentId} — 409 Conflict

Código	Significado	Acción sugerida
AccessRightsChangeRequired	El movimiento cambiaría quién puede acceder al nodo; message explica el cambio específico	Revisa el cambio de acceso, o vuelve a intentarlo con force: true si es aceptable
MaxDepthExceeded	El movimiento excedería la profundidad máxima permitida en la jerarquía	Mueve el nodo a una ubicación menos profunda
CircularityFound	El padre de destino está dentro del subárbol del nodo que se está moviendo	Elige un padre fuera del propio subárbol del nodo
NodeHaveMembershipsAttached	El nodo tiene registros de membresía que bloquean moverlo a través de un límite de permisos	Elimina primero las membresías, o muévelo dentro del mismo ámbito de permisos
NodesInDifferentRegions	El nodo y el padre de destino están provisionados en regiones distintas	No se puede resolver — los nodos no pueden moverse entre regiones
NodeCannotBeMoved	Este tipo de nodo no admite ser movido	No se puede resolver para este tipo de nodo
DerivativesNotInCommonParent	Los derivados del nodo no están todos bajo un padre común con el destino del movimiento	Reorganiza los derivados y vuelve a intentarlo
SourcesNotInCommonParent	Las fuentes del nodo no están todas bajo un padre común	Reorganiza las fuentes y vuelve a intentarlo
DataBundleLinkedToTwin	El Data Bundle del nodo está vinculado a un twin	Desvincula primero el twin
DoesNotMeetHierarchyConstraints	El movimiento viola una regla de jerarquía específica del tipo	Revisa qué tipos hijo admite el padre de destino
MoveNodeFailed	El movimiento se rechazó por un motivo sin un código más específico	Vuelve a intentarlo; contacta con soporte si persiste

Eliminar un nodo

DELETE /v1/nodes/{nodeId} — 409 Conflict

Código	Significado	Acción sugerida
NodeHasDerivatives	El nodo tiene derivados que deben eliminarse primero, listados en derivatives[]	Elimina o mueve los derivados listados y vuelve a intentarlo
NodeNotInDeletableState	El nodo está actualmente en procesamiento o el procesamiento falló, según isProcessing / isFailed	Espera a que termine el procesamiento, o resuelve el fallo, y vuelve a intentarlo
NodeHasBundleDependants	El Data Bundle del nodo tiene dependientes que bloquean la eliminación	Elimina primero los dependientes
DeleteNodeFailed	La eliminación se rechazó por un motivo sin un código más específico	Vuelve a intentarlo; contacta con soporte si persiste

Restaurar o eliminar permanentemente un nodo en la papelera

Endpoint	Estado	Código	Significado	Acción sugerida
PATCH /v1/nodes/{id}/restore	409	StorageLimitExceeded	Restaurar el nodo excedería la cuota de almacenamiento de la organización	Libera espacio o aumenta la cuota, y vuelve a intentarlo
DELETE /v1/nodes/{id}/hard	409	NoNodeRemoved	El nodo no se encontró en la papelera en un estado eliminable	Verifica el id del nodo y su estado en la papelera

Procesamiento de Data Bundles

POST /v1/bundles/{bundleId}/processing — 409 Conflict

Código	Significado	Acción sugerida
ProcessingCostMismatch	El costo de procesamiento enviado ya no coincide con el costo actual	Obtén una nueva estimación de costo y vuelve a intentarlo
NoInputDataFoundForProcessing	No se encontraron datos de entrada para procesar en este Data Bundle	Verifica que la sesión de carga se haya finalizado antes de lanzar el procesamiento
InsufficientProcessingCapacity	La capacidad de procesamiento no está disponible en este momento	Vuelve a intentarlo más tarde
FailedToLaunchProcessing	No se pudo lanzar el trabajo de procesamiento	Vuelve a intentarlo; contacta con soporte si persiste

Cargas de archivos

Endpoint	Estado	Código	Significado	Acción sugerida
POST /v1/site-files	403	StorageLimitExceeded	Se excedió la cuota de almacenamiento de la organización	Libera espacio o aumenta la cuota
POST /v1/site-files	409	FileAlreadyExists	Ya existe un archivo con la misma identidad	Usa el archivo existente, o sube uno con un nombre distinto
POST /v1/site-files/{fileId}/finalize	400	FileNotCompatible	El formato del archivo subido no es compatible con el tipo de archivo esperado	Verifica el formato del archivo y vuelve a subirlo
POST /v1/bundles/{bundleId}/upload-sessions	403	StorageLimitExceeded	Se excedió la cuota de almacenamiento de la organización	Libera espacio o aumenta la cuota
POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files	403	StorageLimitExceeded	Se excedió la cuota de almacenamiento de la organización	Libera espacio o aumenta la cuota
POST /v1/twin/{contextId}/object/attachments	409	StorageLimitExceeded	Se excedió la cuota de almacenamiento de la organización	Libera espacio o aumenta la cuota
POST /v1/twin/{contextId}/object/attachments	409	FileAlreadyExists	Ya existe un adjunto con la misma identidad	Usa el adjunto existente, o sube uno con un nombre distinto

Grupos

Membresía de grupo

PUT /v1/groups/{groupId}/users/{userId} (agregar un miembro) — 409 Conflict

Código	Significado	Acción sugerida
GroupHasSamlLink	La membresía del grupo se gestiona mediante una integración SAML/SSO	Gestiona la membresía a través del proveedor SAML
CannotInviteToSCIMGroup	La membresía del grupo se gestiona mediante aprovisionamiento SCIM	Gestiona la membresía a través del proveedor SCIM
UserAlreadyMember	El usuario ya es miembro del grupo	No se necesita ninguna acción

DELETE /v1/groups/{groupId}/users/{userId} (eliminar un miembro) — 409 Conflict

Código	Significado	Acción sugerida
GroupHasSamlLink	La membresía del grupo se gestiona mediante una integración SAML/SSO	Gestiona la membresía a través del proveedor SAML
CannotRemoveMemberFromSCIMGroup	La membresía del grupo se gestiona mediante aprovisionamiento SCIM	Gestiona la membresía a través del proveedor SCIM

Crear, renombrar y eliminar grupos

POST /v1/groups y PATCH /v1/groups/{groupId} — 409 Conflict

Código	Significado	Acción sugerida
DuplicateGroupName	Ya existe un grupo con este nombre en la organización	Elige un nombre distinto
CannotUpdateMemberFromSCIMGroup	La membresía del grupo se gestiona mediante aprovisionamiento SCIM	Gestiona la membresía a través del proveedor SCIM

DELETE /v1/groups/{groupId} — 409 Conflict

Código	Significado	Acción sugerida
CannotRemoveSCIMGroup	La membresía del grupo se gestiona mediante aprovisionamiento SCIM	Gestiona la membresía a través del proveedor SCIM
CannotRemoveOrganizationGroup	El grupo no tiene una única división propietaria	No se puede resolver — este grupo no se puede eliminar mediante este endpoint

Invitaciones a nodos y a la organización

POST /v1/nodes/{nodeId}/invitations y POST /v1/invitations comparten los mismos códigos de error.

Estado	Código	Significado	Acción sugerida
409	UserAlreadyInvited	El usuario ya tiene una invitación pendiente	No se necesita ninguna acción
409	UserAlreadyMember	El usuario ya es miembro	No se necesita ninguna acción
403	InvalidEmailDomain	El dominio del correo invitado no está permitido para esta organización	Usa una dirección de correo con un dominio permitido
400	CustomRoleNotAssignableToDataNode	El rol personalizado especificado no se puede asignar en este nodo	Elige un rol asignable en este nodo
400	CustomRoleNotFound	El rol personalizado especificado no existe	Verifica el id del rol
400	AdminsitrativeRoleNotFound*	El rol administrativo especificado no existe	Verifica el id del rol
400	AdministrativeRoleInvalidNode	Se dirigió un rol administrativo a un nodo que no lo admite	Asigna el rol administrativo a nivel de organización en su lugar
422	InvitationEmailRejected	El proveedor de correo rechazó permanentemente la dirección del destinatario	Corrige la dirección de correo antes de volver a intentarlo
503	InvitationEmailNotSent	El proveedor de correo no está disponible temporalmente; no se persistió nada	Vuelve a intentar la solicitud tal cual

* Este nombre de código lleva un error de tipeo en la respuesta actual de la API — cópialo exactamente como se muestra, no AdministrativeRoleNotFound.

Límite de tasa, autenticación y control de acceso

Un 403 puede provenir de cualquiera de las tres capas de control de acceso descritas en Primeros pasos — Modelo de seguridad: ámbitos de OAuth, roles por nodo y acceso al contenido. Las tres comparten actualmente el mismo código de estado, y la mayoría comparte el mismo cuerpo genérico, así que trata un 403 como “no autorizado por alguno de estos motivos” en lugar de asumir que siempre es un problema de ámbito.

Estado	Código	Significado
429	rate_limited	Se agotó el bucket de solicitudes de la organización — consulta Límites de tasa
401	not_authenticated	A la solicitud le falta un token bearer, o el token no se pudo analizar
401	invalid_token	Falló la verificación de firma o expiración del token
403	(sin código — mensaje: "Insufficient OAuth scopes")	El token no tiene un ámbito que la operación requiere — consulta Ámbitos de OAuth
403	(sin código — mensaje: "Forbidden resource")	El rol o el acceso al contenido del solicitante en este nodo no permite la acción, o la organización alcanzó un límite de licencias/asientos — el cuerpo no distingue cuál
403	errorCode: "SSORestrictedResource"	Este recurso está restringido a quienes se autentican mediante una sesión específica de SSO/proveedor de identidad

¿Qué sigue?

• Consulta la referencia de la API para ver los esquemas completos de solicitud y respuesta de cada operación.