오류 코드

표준 HTTP 상태 코드 외에도, 여러 RealityConnect API 작업은 요청이 거부된 이유를 구분하기 위해 응답 본문에 기계 판독 가능한 error 코드를 반환합니다. 이 페이지는 엔드포인트별로 모든 명명된 코드를 정리하고, 각 코드를 유발하는 원인과 처리 방법을 설명합니다.

응답 형식

명명된 코드를 반환하는 작업은 다음 형식을 사용하며, 엔드포인트별 추가 필드는 아래에 표시됩니다:

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

message는 선택 사항이며, 있는 경우 사람이 읽을 수 있는 세부 정보를 제공합니다. 처리 로직은 message가 아닌 error를 기준으로 분기하세요.

데이터 노드 계층 구조

노드 이동

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

코드	의미	권장 조치
`AccessRightsChangeRequired`	이동으로 인해 노드에 접근할 수 있는 사용자가 변경됩니다; `message`에 구체적인 변경 내용이 설명됩니다	접근 권한 변경 사항을 검토하거나, 허용 가능하다면 `force: true`로 다시 시도하세요
`MaxDepthExceeded`	이동하면 허용된 최대 계층 깊이를 초과합니다	더 얕은 위치로 노드를 이동하세요
`CircularityFound`	대상 부모가 이동 중인 노드의 하위 트리 내에 있습니다	노드 자신의 하위 트리 밖에 있는 부모를 선택하세요
`NodeHaveMembershipsAttached`	노드에 권한 경계를 넘는 이동을 막는 멤버십 레코드가 있습니다	멤버십을 먼저 제거하거나, 동일한 권한 범위 내에서 이동하세요
`NodesInDifferentRegions`	노드와 대상 부모가 서로 다른 리전에 프로비저닝되어 있습니다	해결할 수 없음 — 노드는 리전 간에 이동할 수 없습니다
`NodeCannotBeMoved`	이 노드 유형은 이동을 지원하지 않습니다	이 노드 유형에서는 해결할 수 없음
`DerivativesNotInCommonParent`	노드의 파생 출력물이 이동 대상과 동일한 부모 아래에 모두 있지 않습니다	파생물을 재구성한 다음 다시 시도하세요
`SourcesNotInCommonParent`	노드의 소스 입력이 모두 공통 부모 아래에 있지 않습니다	소스를 재구성한 다음 다시 시도하세요
`DataBundleLinkedToTwin`	노드의 데이터 번들이 트윈에 연결되어 있습니다	먼저 트윈 연결을 해제하세요
`DoesNotMeetHierarchyConstraints`	이동이 유형별 계층 규칙을 위반합니다	대상 부모가 허용하는 하위 유형을 확인하세요
`MoveNodeFailed`	더 구체적인 코드 없이 이동이 거부되었습니다	다시 시도하세요; 계속되면 지원팀에 문의하세요

노드 삭제

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

코드	의미	권장 조치
`NodeHasDerivatives`	노드에 먼저 제거해야 하는 파생 출력물이 있으며, `derivatives[]`에 나열됩니다	나열된 파생물을 삭제하거나 이동한 다음 다시 시도하세요
`NodeNotInDeletableState`	노드가 현재 처리 중이거나 처리에 실패했습니다 (`isProcessing`/`isFailed` 참조)	처리가 완료되기를 기다리거나 실패를 해결한 다음 다시 시도하세요
`NodeHasBundleDependants`	노드의 데이터 번들에 삭제를 막는 종속 항목이 있습니다	종속 항목을 먼저 제거하세요
`DeleteNodeFailed`	더 구체적인 코드 없이 삭제가 거부되었습니다	다시 시도하세요; 계속되면 지원팀에 문의하세요

휴지통에 있는 노드 복원 또는 영구 삭제

엔드포인트	상태	코드	의미	권장 조치
`PATCH /v1/nodes/{id}/restore`	409	`StorageLimitExceeded`	노드를 복원하면 조직의 스토리지 할당량을 초과합니다	스토리지를 확보하거나 할당량을 늘린 다음 다시 시도하세요
`DELETE /v1/nodes/{id}/hard`	409	`NoNodeRemoved`	노드가 삭제 가능한 상태로 휴지통에서 발견되지 않았습니다	노드 ID와 휴지통 상태를 확인하세요

데이터 번들 처리

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

코드	의미	권장 조치
`ProcessingCostMismatch`	제출된 처리 비용이 현재 비용과 더 이상 일치하지 않습니다	새로운 비용 견적을 가져와 다시 시도하세요
`NoInputDataFoundForProcessing`	이 번들을 처리할 입력 데이터를 찾을 수 없습니다	처리를 시작하기 전에 업로드 세션이 완료되었는지 확인하세요
`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`	동일한 식별자를 가진 첨부 파일이 이미 존재합니다	기존 첨부 파일을 사용하거나 다른 이름으로 업로드하세요

그룹

그룹 멤버십

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 공급자를 통해 멤버십을 관리하세요

그룹 생성, 이름 변경, 삭제

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

코드	의미	권장 조치
`DuplicateGroupName`	조직에 이 이름을 가진 그룹이 이미 존재합니다	다른 이름을 선택하세요
`CannotUpdateMemberFromSCIMGroup`	그룹의 멤버십이 SCIM 프로비저닝으로 관리됩니다	SCIM 공급자를 통해 멤버십을 관리하세요

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

코드	의미	권장 조치
`CannotRemoveSCIMGroup`	그룹의 멤버십이 SCIM 프로비저닝으로 관리됩니다	SCIM 공급자를 통해 멤버십을 관리하세요
`CannotRemoveOrganizationGroup`	그룹을 단독으로 소유하는 디비전이 없습니다	해결할 수 없음 — 이 엔드포인트로는 이 그룹을 삭제할 수 없습니다

노드 및 조직 초대

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가 아니라 표시된 그대로 정확히 일치시키세요.

속도 제한, 인증, 접근 제어

403은 보안 모델에서 설명하는 세 가지 접근 제어 계층(OAuth 스코프, 노드별 역할, 콘텐츠 접근) 중 어느 것에서든 발생할 수 있습니다. 현재 이 세 가지는 모두 동일한 상태 코드를 사용하며, 대부분 동일한 일반적인 본문을 공유합니다. 따라서 403을 항상 스코프 문제로 간주하지 말고 “이러한 이유 중 하나로 인해 권한이 없음”으로 처리하세요.

상태	코드	의미
429	`rate_limited`	조직의 요청 버킷이 소진되었습니다 — 속도 제한 참조
401	`not_authenticated`	요청에 베어러 토큰이 없거나 토큰을 구문 분석할 수 없습니다
401	`invalid_token`	토큰의 서명 또는 만료 확인이 실패했습니다
403	(코드 없음 — message: `"Insufficient OAuth scopes"`)	토큰에 이 작업에 필요한 스코프가 없습니다 — OAuth 스코프 참조
403	(코드 없음 — message: `"Forbidden resource"`)	호출자의 역할이나 이 노드에 대한 콘텐츠 접근 권한이 작업을 허용하지 않거나, 조직이 라이선스/좌석 한도에 도달했습니다 — 본문으로는 어느 쪽인지 구분할 수 없습니다
403	`errorCode: "SSORestrictedResource"`	이 리소스는 특정 SSO/자격 증명 공급자 세션으로 인증된 호출자로 제한됩니다

다음은?

각 작업의 전체 요청 및 응답 스키마는 API 참조를 참조하세요.