Error Codes

Beyond standard HTTP status codes, several RealityConnect API operations return a machine-readable error code in the response body to disambiguate why a request was rejected. This page catalogs every named code by endpoint, what triggers it, and how to handle it.

---

Response shape

Operations that return a named code use this shape, with extra context-specific fields noted per endpoint below:

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

message is optional and, where present, gives a human-readable detail. Branch your handling on error, not on message.

Data node hierarchy

Move a node

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

Code	Meaning	Suggested action
AccessRightsChangeRequired	The move would change who can access the node; message explains the specific change	Review the access change, or retry with force: true if it is acceptable
MaxDepthExceeded	The move would exceed the maximum allowed hierarchy depth	Move the node to a shallower location
CircularityFound	The target parent is inside the subtree of the node being moved	Choose a parent outside the node’s own subtree
NodeHaveMembershipsAttached	The node has membership records that block moving it across a permission boundary	Remove the memberships first, or move within the same permission scope
NodesInDifferentRegions	The node and the target parent are provisioned in different regions	Not resolvable — nodes cannot move across regions
NodeCannotBeMoved	This node type does not support being moved	Not resolvable for this node type
DerivativesNotInCommonParent	The node’s derivative outputs are not all under a common parent with the move target	Reorganize the derivatives, then retry
SourcesNotInCommonParent	The node’s source inputs are not all under a common parent	Reorganize the sources, then retry
DataBundleLinkedToTwin	The node’s data bundle is linked to a twin	Unlink the twin first
DoesNotMeetHierarchyConstraints	The move violates a type-specific hierarchy rule	Check which child types the target parent allows
MoveNodeFailed	The move was rejected for a reason with no more specific code	Retry; contact support if it persists

Delete a node

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

Code	Meaning	Suggested action
NodeHasDerivatives	The node has derivative outputs that must be removed first, listed in derivatives[]	Delete or move the listed derivatives, then retry
NodeNotInDeletableState	The node is currently processing or failed processing, per isProcessing / isFailed	Wait for processing to finish, or resolve the failure, then retry
NodeHasBundleDependants	The node’s data bundle has dependants that block deletion	Remove the dependants first
DeleteNodeFailed	The delete was rejected for a reason with no more specific code	Retry; contact support if it persists

Restore or permanently delete a trashed node

Endpoint	Status	Code	Meaning	Suggested action
PATCH /v1/nodes/{id}/restore	409	StorageLimitExceeded	Restoring the node would exceed the organization’s storage quota	Free up storage or increase the quota, then retry
DELETE /v1/nodes/{id}/hard	409	NoNodeRemoved	The node was not found in the trash in a removable state	Verify the node id and its trash state

Data bundle processing

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

Code	Meaning	Suggested action
ProcessingCostMismatch	The submitted processing cost no longer matches the current cost	Fetch a fresh cost estimate and retry
NoInputDataFoundForProcessing	No input data was found for this bundle to process	Verify the upload session finalized before triggering processing
InsufficientProcessingCapacity	Processing capacity is not currently available	Retry later
FailedToLaunchProcessing	The processing job could not be launched	Retry; contact support if it persists

File uploads

Endpoint	Status	Code	Meaning	Suggested action
POST /v1/site-files	403	StorageLimitExceeded	The organization’s storage quota is exceeded	Free up storage or increase the quota
POST /v1/site-files	409	FileAlreadyExists	A file with the same identity already exists	Use the existing file, or upload under a different name
POST /v1/site-files/{fileId}/finalize	400	FileNotCompatible	The uploaded file’s format is not compatible with the expected file type	Verify the file format and re-upload
POST /v1/bundles/{bundleId}/upload-sessions	403	StorageLimitExceeded	The organization’s storage quota is exceeded	Free up storage or increase the quota
POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files	403	StorageLimitExceeded	The organization’s storage quota is exceeded	Free up storage or increase the quota
POST /v1/twin/{contextId}/object/attachments	409	StorageLimitExceeded	The organization’s storage quota is exceeded	Free up storage or increase the quota
POST /v1/twin/{contextId}/object/attachments	409	FileAlreadyExists	An attachment with the same identity already exists	Use the existing attachment, or upload under a different name

Groups

Group membership

PUT /v1/groups/{groupId}/users/{userId} (add a member) — 409 Conflict

Code	Meaning	Suggested action
GroupHasSamlLink	The group’s membership is managed by a SAML/SSO integration	Manage membership through the SAML provider
CannotInviteToSCIMGroup	The group’s membership is managed by SCIM provisioning	Manage membership through the SCIM provider
UserAlreadyMember	The user is already a member of the group	No action needed

DELETE /v1/groups/{groupId}/users/{userId} (remove a member) — 409 Conflict

Code	Meaning	Suggested action
GroupHasSamlLink	The group’s membership is managed by a SAML/SSO integration	Manage membership through the SAML provider
CannotRemoveMemberFromSCIMGroup	The group’s membership is managed by SCIM provisioning	Manage membership through the SCIM provider

Creating, renaming, and deleting groups

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

Code	Meaning	Suggested action
DuplicateGroupName	A group with this name already exists in the organization	Choose a different name
CannotUpdateMemberFromSCIMGroup	The group’s membership is managed by SCIM provisioning	Manage membership through the SCIM provider

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

Code	Meaning	Suggested action
CannotRemoveSCIMGroup	The group’s membership is managed by SCIM provisioning	Manage membership through the SCIM provider
CannotRemoveOrganizationGroup	The group has no single owning division	Not resolvable — this group cannot be deleted through this endpoint

Node and organization invitations

POST /v1/nodes/{nodeId}/invitations and POST /v1/invitations share the same error codes.

Status	Code	Meaning	Suggested action
409	UserAlreadyInvited	The user already has a pending invitation	No action needed
409	UserAlreadyMember	The user is already a member	No action needed
403	InvalidEmailDomain	The invited email’s domain is not allowed for this organization	Use an email address on an allowed domain
400	CustomRoleNotAssignableToDataNode	The specified custom role cannot be assigned at this node	Choose a role assignable at this node
400	CustomRoleNotFound	The specified custom role does not exist	Verify the role id
400	AdminsitrativeRoleNotFound*	The specified administrative role does not exist	Verify the role id
400	AdministrativeRoleInvalidNode	An administrative role was targeted at a node that does not support it	Assign the administrative role at the organization level instead
422	InvitationEmailRejected	The mail provider permanently rejected the recipient address	Correct the email address before retrying
503	InvitationEmailNotSent	The mail provider is temporarily unavailable; nothing was persisted	Retry the request as-is

* This code name carries a typo in the API’s current response — match it exactly as shown, not AdministrativeRoleNotFound.

Rate limiting, authentication, and access control

A 403 can come from any of the three access-control layers described in Getting Started — Security Model: OAuth scopes, per-node roles, and content access. All three currently share the same status code, and most of them share the same generic body, so treat a 403 as “not authorized for one of these reasons” rather than assuming it is always a scope problem.

Status	Code	Meaning
429	rate_limited	The organization’s request bucket is exhausted — see Rate Limits
401	not_authenticated	The request is missing a bearer token, or the token could not be parsed
401	invalid_token	The token’s signature or expiry check failed
403	(no code — message: "Insufficient OAuth scopes")	The token does not carry a scope the operation requires — see OAuth Scopes
403	(no code — message: "Forbidden resource")	The caller’s role or content access on this node does not permit the action, or the organization has hit a licensing/seat limit — the body does not distinguish which
403	errorCode: "SSORestrictedResource"	This resource is restricted to callers authenticated through a specific SSO/identity-provider session

What’s next?

• See the API reference for full request and response schemas per operation.