Fehlercodes

Über die Standard-HTTP-Statuscodes hinaus geben mehrere Operationen der RealityConnect API einen maschinenlesbaren error-Code im Antwortkörper zurück, um eindeutig anzugeben, warum eine Anfrage abgelehnt wurde. Diese Seite katalogisiert jeden benannten Code nach Endpunkt, was ihn auslöst und wie er zu behandeln ist.

---

Antwortformat

Operationen, die einen benannten Code zurückgeben, verwenden dieses Format; zusätzliche kontextspezifische Felder werden unten pro Endpunkt vermerkt:

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

message ist optional und liefert, wenn vorhanden, eine menschenlesbare Detailangabe. Richten Sie Ihre Behandlung nach error, nicht nach message.

Datenknoten-Hierarchie

Knoten verschieben

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

Code	Bedeutung	Empfohlene Aktion
AccessRightsChangeRequired	Das Verschieben würde ändern, wer auf den Knoten zugreifen kann; message erläutert die konkrete Änderung	Prüfen Sie die Zugriffsänderung, oder wiederholen Sie die Anfrage mit force: true, falls akzeptabel
MaxDepthExceeded	Das Verschieben würde die maximal zulässige Hierarchietiefe überschreiten	Verschieben Sie den Knoten an eine flachere Position
CircularityFound	Das Zielelternelement befindet sich innerhalb des Teilbaums des zu verschiebenden Knotens	Wählen Sie ein Elternelement außerhalb des eigenen Teilbaums des Knotens
NodeHaveMembershipsAttached	Der Knoten verfügt über Mitgliedschaftseinträge, die das Verschieben über eine Berechtigungsgrenze hinweg blockieren	Entfernen Sie zuerst die Mitgliedschaften, oder verschieben Sie innerhalb desselben Berechtigungsbereichs
NodesInDifferentRegions	Der Knoten und das Zielelternelement sind in unterschiedlichen Regionen bereitgestellt	Nicht behebbar — Knoten können nicht regionsübergreifend verschoben werden
NodeCannotBeMoved	Dieser Knotentyp unterstützt kein Verschieben	Für diesen Knotentyp nicht behebbar
DerivativesNotInCommonParent	Die abgeleiteten Ausgaben des Knotens befinden sich nicht alle unter einem gemeinsamen Elternelement mit dem Verschiebeziel	Organisieren Sie die abgeleiteten Objekte neu und wiederholen Sie dann die Anfrage
SourcesNotInCommonParent	Die Quelleingaben des Knotens befinden sich nicht alle unter einem gemeinsamen Elternelement	Organisieren Sie die Quellen neu und wiederholen Sie dann die Anfrage
DataBundleLinkedToTwin	Das Data Bundle des Knotens ist mit einem Twin verknüpft	Heben Sie zuerst die Verknüpfung mit dem Twin auf
DoesNotMeetHierarchyConstraints	Das Verschieben verstößt gegen eine typspezifische Hierarchieregel	Prüfen Sie, welche untergeordneten Typen das Zielelternelement zulässt
MoveNodeFailed	Das Verschieben wurde aus einem Grund abgelehnt, für den kein spezifischerer Code vorliegt	Wiederholen Sie die Anfrage; wenden Sie sich an den Support, falls das Problem weiterhin besteht

Knoten löschen

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

Code	Bedeutung	Empfohlene Aktion
NodeHasDerivatives	Der Knoten hat abgeleitete Ausgaben, die zuerst entfernt werden müssen; aufgeführt in derivatives[]	Löschen oder verschieben Sie die aufgeführten abgeleiteten Objekte und wiederholen Sie dann die Anfrage
NodeNotInDeletableState	Der Knoten wird derzeit verarbeitet, oder die Verarbeitung ist fehlgeschlagen, gemäß isProcessing / isFailed	Warten Sie, bis die Verarbeitung abgeschlossen ist, oder beheben Sie den Fehler, und wiederholen Sie dann die Anfrage
NodeHasBundleDependants	Das Data Bundle des Knotens hat abhängige Objekte, die das Löschen blockieren	Entfernen Sie zuerst die abhängigen Objekte
DeleteNodeFailed	Das Löschen wurde aus einem Grund abgelehnt, für den kein spezifischerer Code vorliegt	Wiederholen Sie die Anfrage; wenden Sie sich an den Support, falls das Problem weiterhin besteht

Knoten im Papierkorb wiederherstellen oder endgültig löschen

Endpunkt	Status	Code	Bedeutung	Empfohlene Aktion
PATCH /v1/nodes/{id}/restore	409	StorageLimitExceeded	Das Wiederherstellen des Knotens würde das Speicherkontingent der Organisation überschreiten	Geben Sie Speicherplatz frei oder erhöhen Sie das Kontingent, und wiederholen Sie dann die Anfrage
DELETE /v1/nodes/{id}/hard	409	NoNodeRemoved	Der Knoten wurde im Papierkorb nicht in einem löschbaren Zustand gefunden	Überprüfen Sie die Knoten-ID und deren Papierkorbstatus

Data-Bundle-Verarbeitung

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

Code	Bedeutung	Empfohlene Aktion
ProcessingCostMismatch	Die übermittelten Verarbeitungskosten stimmen nicht mehr mit den aktuellen Kosten überein	Rufen Sie eine aktuelle Kostenschätzung ab und wiederholen Sie die Anfrage
NoInputDataFoundForProcessing	Für dieses Bundle wurden keine zu verarbeitenden Eingabedaten gefunden	Stellen Sie sicher, dass die Upload-Sitzung abgeschlossen wurde, bevor Sie die Verarbeitung auslösen
InsufficientProcessingCapacity	Derzeit ist keine Verarbeitungskapazität verfügbar	Versuchen Sie es später erneut
FailedToLaunchProcessing	Der Verarbeitungsjob konnte nicht gestartet werden	Wiederholen Sie die Anfrage; wenden Sie sich an den Support, falls das Problem weiterhin besteht

Datei-Uploads

Endpunkt	Status	Code	Bedeutung	Empfohlene Aktion
POST /v1/site-files	403	StorageLimitExceeded	Das Speicherkontingent der Organisation ist ausgeschöpft	Geben Sie Speicherplatz frei oder erhöhen Sie das Kontingent
POST /v1/site-files	409	FileAlreadyExists	Es existiert bereits eine Datei mit derselben Identität	Verwenden Sie die vorhandene Datei, oder laden Sie sie unter einem anderen Namen hoch
POST /v1/site-files/{fileId}/finalize	400	FileNotCompatible	Das Format der hochgeladenen Datei ist mit dem erwarteten Dateityp nicht kompatibel	Überprüfen Sie das Dateiformat und laden Sie die Datei erneut hoch
POST /v1/bundles/{bundleId}/upload-sessions	403	StorageLimitExceeded	Das Speicherkontingent der Organisation ist ausgeschöpft	Geben Sie Speicherplatz frei oder erhöhen Sie das Kontingent
POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files	403	StorageLimitExceeded	Das Speicherkontingent der Organisation ist ausgeschöpft	Geben Sie Speicherplatz frei oder erhöhen Sie das Kontingent
POST /v1/twin/{contextId}/object/attachments	409	StorageLimitExceeded	Das Speicherkontingent der Organisation ist ausgeschöpft	Geben Sie Speicherplatz frei oder erhöhen Sie das Kontingent
POST /v1/twin/{contextId}/object/attachments	409	FileAlreadyExists	Es existiert bereits ein Anhang mit derselben Identität	Verwenden Sie den vorhandenen Anhang, oder laden Sie ihn unter einem anderen Namen hoch

Gruppen

Gruppenmitgliedschaft

PUT /v1/groups/{groupId}/users/{userId} (Mitglied hinzufügen) — 409 Conflict

Code	Bedeutung	Empfohlene Aktion
GroupHasSamlLink	Die Mitgliedschaft der Gruppe wird über eine SAML/SSO-Integration verwaltet	Verwalten Sie die Mitgliedschaft über den SAML-Anbieter
CannotInviteToSCIMGroup	Die Mitgliedschaft der Gruppe wird über SCIM-Provisioning verwaltet	Verwalten Sie die Mitgliedschaft über den SCIM-Anbieter
UserAlreadyMember	Der Benutzer ist bereits Mitglied der Gruppe	Keine Aktion erforderlich

DELETE /v1/groups/{groupId}/users/{userId} (Mitglied entfernen) — 409 Conflict

Code	Bedeutung	Empfohlene Aktion
GroupHasSamlLink	Die Mitgliedschaft der Gruppe wird über eine SAML/SSO-Integration verwaltet	Verwalten Sie die Mitgliedschaft über den SAML-Anbieter
CannotRemoveMemberFromSCIMGroup	Die Mitgliedschaft der Gruppe wird über SCIM-Provisioning verwaltet	Verwalten Sie die Mitgliedschaft über den SCIM-Anbieter

Gruppen erstellen, umbenennen und löschen

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

Code	Bedeutung	Empfohlene Aktion
DuplicateGroupName	In der Organisation existiert bereits eine Gruppe mit diesem Namen	Wählen Sie einen anderen Namen
CannotUpdateMemberFromSCIMGroup	Die Mitgliedschaft der Gruppe wird über SCIM-Provisioning verwaltet	Verwalten Sie die Mitgliedschaft über den SCIM-Anbieter

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

Code	Bedeutung	Empfohlene Aktion
CannotRemoveSCIMGroup	Die Mitgliedschaft der Gruppe wird über SCIM-Provisioning verwaltet	Verwalten Sie die Mitgliedschaft über den SCIM-Anbieter
CannotRemoveOrganizationGroup	Die Gruppe hat keine einzelne zugehörige Division	Nicht behebbar — diese Gruppe kann nicht über diesen Endpunkt gelöscht werden

Knoten- und Organisationseinladungen

POST /v1/nodes/{nodeId}/invitations und POST /v1/invitations verwenden dieselben Fehlercodes.

Status	Code	Bedeutung	Empfohlene Aktion
409	UserAlreadyInvited	Für den Benutzer liegt bereits eine ausstehende Einladung vor	Keine Aktion erforderlich
409	UserAlreadyMember	Der Benutzer ist bereits Mitglied	Keine Aktion erforderlich
403	InvalidEmailDomain	Die Domain der eingeladenen E-Mail-Adresse ist für diese Organisation nicht zulässig	Verwenden Sie eine E-Mail-Adresse mit einer zulässigen Domain
400	CustomRoleNotAssignableToDataNode	Die angegebene benutzerdefinierte Rolle kann diesem Knoten nicht zugewiesen werden	Wählen Sie eine Rolle, die diesem Knoten zugewiesen werden kann
400	CustomRoleNotFound	Die angegebene benutzerdefinierte Rolle existiert nicht	Überprüfen Sie die Rollen-ID
400	AdminsitrativeRoleNotFound*	Die angegebene administrative Rolle existiert nicht	Überprüfen Sie die Rollen-ID
400	AdministrativeRoleInvalidNode	Eine administrative Rolle wurde auf einen Knoten angewendet, der dies nicht unterstützt	Weisen Sie die administrative Rolle statt dessen auf Organisationsebene zu
422	InvitationEmailRejected	Der Mailanbieter hat die Empfängeradresse dauerhaft abgelehnt	Korrigieren Sie die E-Mail-Adresse, bevor Sie es erneut versuchen
503	InvitationEmailNotSent	Der Mailanbieter ist vorübergehend nicht verfügbar; es wurde nichts gespeichert	Wiederholen Sie die Anfrage unverändert

* Dieser Codename enthält einen Tippfehler in der aktuellen API-Antwort — verwenden Sie ihn exakt wie angegeben, nicht AdministrativeRoleNotFound.

Ratenbegrenzung, Authentifizierung und Zugriffskontrolle

Ein 403 kann von einer der drei in Erste Schritte — Sicherheitsmodell beschriebenen Zugriffskontrollebenen stammen: OAuth-Scopes, knotenbezogene Rollen und Inhaltszugriff. Alle drei verwenden derzeit denselben Statuscode, und die meisten teilen sich denselben generischen Antwortkörper. Behandeln Sie ein 403 daher als „aus einem dieser Gründe nicht autorisiert“ und nicht als reines Scope-Problem.

Status	Code	Bedeutung
429	rate_limited	Der Anfragen-Bucket der Organisation ist ausgeschöpft — siehe Rate Limits
401	not_authenticated	Der Anfrage fehlt ein Bearer-Token, oder das Token konnte nicht verarbeitet werden
401	invalid_token	Die Signatur- oder Ablaufprüfung des Tokens ist fehlgeschlagen
403	(kein Code — message: "Insufficient OAuth scopes")	Das Token enthält nicht den vom Vorgang benötigten Scope — siehe OAuth-Scopes-Referenz
403	(kein Code — message: "Forbidden resource")	Die Rolle oder der Inhaltszugriff des Aufrufers auf diesen Knoten erlaubt die Aktion nicht, oder die Organisation hat ein Lizenz-/Platzlimit erreicht — der Antwortkörper unterscheidet nicht, welcher Fall zutrifft
403	errorCode: "SSORestrictedResource"	Diese Ressource ist auf Aufrufer beschränkt, die über eine bestimmte SSO-/Identity-Provider-Sitzung authentifiziert sind

Wie geht es weiter?

• Siehe die API-Referenz für vollständige Anfrage- und Antwortschemata pro Operation.