エラーコード

標準の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は、セキュリティモデルで説明されている3つのアクセス制御レイヤー（OAuthスコープ、ノードごとのロール、コンテンツアクセス）のいずれからも発生する可能性があります。現時点ではこの3つすべてが同じステータスコードを共有し、そのほとんどが同じ汎用的なボディを共有しているため、403を常にスコープの問題と決めつけず、「これらの理由のいずれかにより許可されていない」ものとして扱ってください。

ステータス	コード	意味
429	`rate_limited`	組織のリクエストバケットが枯渇しています — レート制限を参照してください
401	`not_authenticated`	リクエストにベアラートークンがない、またはトークンを解析できません
401	`invalid_token`	トークンの署名または有効期限の検証に失敗しました
403	(コードなし — message: `"Insufficient OAuth scopes"`)	トークンにその操作が必要とするスコープが含まれていません — OAuthスコープを参照してください
403	(コードなし — message: `"Forbidden resource"`)	呼び出し元のロールまたはこのノードへのコンテンツアクセスがその操作を許可していない、あるいは組織がライセンス/シート数の上限に達しています — ボディではどちらかを判別できません
403	`errorCode: "SSORestrictedResource"`	このリソースは、特定のSSO/IDプロバイダーセッションを通じて認証された呼び出し元に制限されています

次のステップ

各操作の完全なリクエストおよびレスポンススキーマについては、APIリファレンスを参照してください。