错误代码
除标准 HTTP 状态码外，RealityConnect API 的多个操作还会在响应体中返回机器可读的 error 代码，用于说明请求被拒绝的具体原因。本页按端点列出了每个命名代码、触发条件以及处理方式。
返回命名代码的操作使用以下结构，各端点特有的额外字段见下文说明：
{ "statusCode": 409, "error": "NodeHasDerivatives", "message": "..."}message 是可选字段，如果存在，会提供一段人类可读的详细说明。请根据 error 而不是 message 来编写处理逻辑。
数据节点层级
Section titled “数据节点层级”PATCH /v1/nodes/{nodeId}/move/{newParentId} — 409 Conflict
| 代码 | 含义 | 建议操作 |
|---|---|---|
AccessRightsChangeRequired | 此次移动会改变可访问该节点的人员；message 会说明具体的变化 | 请审查该访问权限变化，如可接受，可改用 force: true 重试 |
MaxDepthExceeded | 此次移动会超出层级结构允许的最大深度 | 将节点移动到层级更浅的位置 |
CircularityFound | 目标父节点位于被移动节点自身的子树内 | 选择一个位于该节点子树之外的父节点 |
NodeHaveMembershipsAttached | 该节点附带的成员身份记录阻止了跨权限边界的移动 | 先移除相关成员身份，或在同一权限范围内移动 |
NodesInDifferentRegions | 该节点与目标父节点部署在不同的区域 | 无法解决 —— 节点不能跨区域移动 |
NodeCannotBeMoved | 该节点类型不支持移动 | 该节点类型无法解决此问题 |
DerivativesNotInCommonParent | 该节点的衍生输出并非全部位于与移动目标相同的父节点下 | 先重新整理衍生内容，然后重试 |
SourcesNotInCommonParent | 该节点的源输入并非全部位于同一父节点下 | 先重新整理源内容，然后重试 |
DataBundleLinkedToTwin | 该节点的 Data Bundle 已链接到某个 Twin | 请先取消该 Twin 的链接 |
DoesNotMeetHierarchyConstraints | 此次移动违反了特定类型的层级规则 | 检查目标父节点允许的子节点类型 |
MoveNodeFailed | 移动被拒绝，但没有更具体的代码 | 请重试；如问题持续出现，请联系支持团队 |
DELETE /v1/nodes/{nodeId} — 409 Conflict
| 代码 | 含义 | 建议操作 |
|---|---|---|
NodeHasDerivatives | 该节点存在必须先移除的衍生输出，列于 derivatives[] 中 | 先删除或移动列出的衍生内容，然后重试 |
NodeNotInDeletableState | 该节点当前正在处理中，或处理失败，具体见 isProcessing / isFailed | 等待处理完成，或先解决处理失败问题，然后重试 |
NodeHasBundleDependants | 该节点的 Data Bundle 存在阻止删除的依赖项 | 先移除这些依赖项 |
DeleteNodeFailed | 删除被拒绝，但没有更具体的代码 | 请重试；如问题持续出现，请联系支持团队 |
还原或彻底删除回收站中的节点
Section titled “还原或彻底删除回收站中的节点”| 端点 | 状态码 | 代码 | 含义 | 建议操作 |
|---|---|---|---|---|
PATCH /v1/nodes/{id}/restore | 409 | StorageLimitExceeded | 还原该节点会超出组织的存储配额 | 释放存储空间或提高配额，然后重试 |
DELETE /v1/nodes/{id}/hard | 409 | NoNodeRemoved | 在回收站中未找到处于可移除状态的该节点 | 请核实节点 ID 及其在回收站中的状态 |
Data Bundle 处理
Section titled “Data Bundle 处理”POST /v1/bundles/{bundleId}/processing — 409 Conflict
| 代码 | 含义 | 建议操作 |
|---|---|---|
ProcessingCostMismatch | 提交的处理成本与当前成本不一致 | 请获取最新的成本估算后重试 |
NoInputDataFoundForProcessing | 未找到该 Data Bundle 可供处理的输入数据 | 请在触发处理前确认上传会话已完成 |
InsufficientProcessingCapacity | 当前没有可用的处理容量 | 请稍后重试 |
FailedToLaunchProcessing | 无法启动处理任务 | 请重试；如问题持续出现，请联系支持团队 |
| 端点 | 状态码 | 代码 | 含义 | 建议操作 |
|---|---|---|---|---|
POST /v1/site-files | 403 | StorageLimitExceeded | 组织的存储配额已用尽 | 释放存储空间或提高配额 |
POST /v1/site-files | 409 | FileAlreadyExists | 已存在具有相同标识的文件 | 使用现有文件，或以不同名称上传 |
POST /v1/site-files/{fileId}/finalize | 400 | FileNotCompatible | 上传文件的格式与预期的文件类型不兼容 | 请检查文件格式后重新上传 |
POST /v1/bundles/{bundleId}/upload-sessions | 403 | StorageLimitExceeded | 组织的存储配额已用尽 | 释放存储空间或提高配额 |
POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files | 403 | StorageLimitExceeded | 组织的存储配额已用尽 | 释放存储空间或提高配额 |
POST /v1/twin/{contextId}/object/attachments | 409 | StorageLimitExceeded | 组织的存储配额已用尽 | 释放存储空间或提高配额 |
POST /v1/twin/{contextId}/object/attachments | 409 | FileAlreadyExists | 已存在具有相同标识的附件 | 使用现有附件，或以不同名称上传 |
用户组成员身份
Section titled “用户组成员身份”PUT /v1/groups/{groupId}/users/{userId}（添加成员）— 409 Conflict
| 代码 | 含义 | 建议操作 |
|---|---|---|
GroupHasSamlLink | 该用户组的成员身份由 SAML/SSO 集成管理 | 请通过 SAML 提供方管理成员身份 |
CannotInviteToSCIMGroup | 该用户组的成员身份由 SCIM 配置管理 | 请通过 SCIM 提供方管理成员身份 |
UserAlreadyMember | 该用户已是该用户组的成员 | 无需操作 |
DELETE /v1/groups/{groupId}/users/{userId}（移除成员）— 409 Conflict
| 代码 | 含义 | 建议操作 |
|---|---|---|
GroupHasSamlLink | 该用户组的成员身份由 SAML/SSO 集成管理 | 请通过 SAML 提供方管理成员身份 |
CannotRemoveMemberFromSCIMGroup | 该用户组的成员身份由 SCIM 配置管理 | 请通过 SCIM 提供方管理成员身份 |
创建、重命名和删除用户组
Section titled “创建、重命名和删除用户组”POST /v1/groups 和 PATCH /v1/groups/{groupId} — 409 Conflict
| 代码 | 含义 | 建议操作 |
|---|---|---|
DuplicateGroupName | 该组织中已存在同名的用户组 | 请选择其他名称 |
CannotUpdateMemberFromSCIMGroup | 该用户组的成员身份由 SCIM 配置管理 | 请通过 SCIM 提供方管理成员身份 |
DELETE /v1/groups/{groupId} — 409 Conflict
| 代码 | 含义 | 建议操作 |
|---|---|---|
CannotRemoveSCIMGroup | 该用户组的成员身份由 SCIM 配置管理 | 请通过 SCIM 提供方管理成员身份 |
CannotRemoveOrganizationGroup | 该用户组没有唯一的所属分部 | 无法解决 —— 该用户组无法通过此端点删除 |
节点与组织邀请
Section titled “节点与组织邀请”POST /v1/nodes/{nodeId}/invitations 和 POST /v1/invitations 使用相同的错误代码。
| 状态码 | 代码 | 含义 | 建议操作 |
|---|---|---|---|
| 409 | UserAlreadyInvited | 该用户已有一个待处理的邀请 | 无需操作 |
| 409 | UserAlreadyMember | 该用户已是成员 | 无需操作 |
| 403 | InvalidEmailDomain | 受邀邮箱的域名不在该组织允许的范围内 | 请使用允许域名下的邮箱地址 |
| 400 | CustomRoleNotAssignableToDataNode | 指定的自定义角色无法分配给该节点 | 请选择可在该节点分配的角色 |
| 400 | CustomRoleNotFound | 指定的自定义角色不存在 | 请核实角色 ID |
| 400 | AdminsitrativeRoleNotFound* | 指定的管理角色不存在 | 请核实角色 ID |
| 400 | AdministrativeRoleInvalidNode | 管理角色被指定到了不支持该角色的节点上 | 请改在组织级别分配该管理角色 |
| 422 | InvitationEmailRejected | 邮件服务商永久拒绝了该收件地址 | 请更正邮箱地址后再重试 |
| 503 | InvitationEmailNotSent | 邮件服务商暂时不可用；未持久化任何数据 | 请按原样重试该请求 |
* 此代码名称在 API 当前的响应中存在拼写错误 —— 请按图中所示原样匹配，而不是 AdministrativeRoleNotFound。
速率限制、身份验证与访问控制
Section titled “速率限制、身份验证与访问控制”403 可能来自 快速入门 — 安全模型 中描述的三层访问控制中的任意一层：OAuth 作用域、按节点的角色，以及内容访问。目前这三者共用同一个状态码，其中大多数还共用同一种通用响应体，因此应将 403 理解为“因这几种原因之一而未获授权”，而不要一律假定是作用域问题。
| 状态码 | 代码 | 含义 |
|---|---|---|
| 429 | rate_limited | 该组织的请求配额已用尽 —— 参阅速率限制 |
| 401 | not_authenticated | 请求缺少 Bearer 令牌，或该令牌无法解析 |
| 401 | invalid_token | 该令牌的签名或过期校验未通过 |
| 403 | （无代码 —— message："Insufficient OAuth scopes"） | 该令牌未携带此操作所需的作用域 —— 参阅OAuth 作用域 |
| 403 | （无代码 —— message："Forbidden resource"） | 调用方在该节点上的角色或内容访问权限不允许此操作，或组织已达到许可证/席位上限 —— 响应体无法区分具体是哪一种原因 |
| 403 | errorCode: "SSORestrictedResource" | 该资源仅限通过特定 SSO/身份提供商会话进行身份验证的调用方访问 |
下一步是什么？
Section titled “下一步是什么？”- 参阅 API 参考，查看每个操作的完整请求和响应结构。