Foutcodes

Naast standaard HTTP-statuscodes retourneren verschillende RealityConnect API-bewerkingen een machineleesbare error-code in de response body om aan te geven waarom een verzoek is afgewezen. Deze pagina catalogiseert elke benoemde code per endpoint, wat de code veroorzaakt en hoe u deze afhandelt.

---

Responsvorm

Bewerkingen die een benoemde code retourneren, gebruiken deze vorm, met extra contextspecifieke velden per endpoint hieronder:

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

message is optioneel en geeft, indien aanwezig, een leesbare toelichting. Baseer uw afhandeling op error, niet op message.

Datanode-hiërarchie

Een node verplaatsen

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

Code	Betekenis	Aanbevolen actie
AccessRightsChangeRequired	De verplaatsing zou wijzigen wie toegang heeft tot de node; message legt de specifieke wijziging uit	Bekijk de toegangswijziging, of probeer het opnieuw met force: true als dat acceptabel is
MaxDepthExceeded	De verplaatsing zou de maximaal toegestane hiërarchiediepte overschrijden	Verplaats de node naar een minder diepe locatie
CircularityFound	De doelmap ligt binnen de substructuur van de te verplaatsen node	Kies een bovenliggende map buiten de eigen substructuur van de node
NodeHaveMembershipsAttached	De node heeft lidmaatschapsgegevens die het verplaatsen over een rechtengrens heen blokkeren	Verwijder eerst de lidmaatschappen, of verplaats binnen hetzelfde rechtenbereik
NodesInDifferentRegions	De node en de doelmap zijn in verschillende regio’s geprovisioneerd	Niet oplosbaar — nodes kunnen niet tussen regio’s worden verplaatst
NodeCannotBeMoved	Dit nodetype ondersteunt geen verplaatsing	Niet oplosbaar voor dit nodetype
DerivativesNotInCommonParent	De derivaten van de node liggen niet allemaal onder een gemeenschappelijke bovenliggende map met het verplaatsingsdoel	Herorganiseer de derivaten en probeer het opnieuw
SourcesNotInCommonParent	De bronnen van de node liggen niet allemaal onder een gemeenschappelijke bovenliggende map	Herorganiseer de bronnen en probeer het opnieuw
DataBundleLinkedToTwin	De data bundle van de node is gekoppeld aan een twin	Ontkoppel eerst de twin
DoesNotMeetHierarchyConstraints	De verplaatsing schendt een typespecifieke hiërarchieregel	Controleer welke subtypen de doelmap toestaat
MoveNodeFailed	De verplaatsing is afgewezen om een reden zonder specifiekere code	Probeer het opnieuw; neem contact op met support als dit blijft optreden

Een node verwijderen

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

Code	Betekenis	Aanbevolen actie
NodeHasDerivatives	De node heeft derivaten die eerst verwijderd moeten worden, vermeld in derivatives[]	Verwijder of verplaats de vermelde derivaten en probeer het opnieuw
NodeNotInDeletableState	De node wordt momenteel verwerkt of de verwerking is mislukt, zie isProcessing / isFailed	Wacht tot de verwerking is voltooid, of los de fout op, en probeer het opnieuw
NodeHasBundleDependants	De data bundle van de node heeft afhankelijke elementen die verwijdering blokkeren	Verwijder eerst de afhankelijke elementen
DeleteNodeFailed	Het verwijderen is afgewezen om een reden zonder specifiekere code	Probeer het opnieuw; neem contact op met support als dit blijft optreden

Een verwijderde node herstellen of definitief verwijderen

Endpoint	Status	Code	Betekenis	Aanbevolen actie
PATCH /v1/nodes/{id}/restore	409	StorageLimitExceeded	Het herstellen van de node zou de opslagquota van de organisatie overschrijden	Maak opslagruimte vrij of verhoog de quota, en probeer het opnieuw
DELETE /v1/nodes/{id}/hard	409	NoNodeRemoved	De node is niet gevonden in de prullenbak in een verwijderbare status	Controleer de node-id en de status in de prullenbak

Data bundle-verwerking

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

Code	Betekenis	Aanbevolen actie
ProcessingCostMismatch	De opgegeven verwerkingskosten komen niet meer overeen met de huidige kosten	Haal een nieuwe kostenraming op en probeer het opnieuw
NoInputDataFoundForProcessing	Er zijn geen invoergegevens gevonden om voor deze bundle te verwerken	Controleer of de uploadsessie is afgerond voordat verwerking wordt gestart
InsufficientProcessingCapacity	Er is momenteel geen verwerkingscapaciteit beschikbaar	Probeer het later opnieuw
FailedToLaunchProcessing	De verwerkingstaak kon niet worden gestart	Probeer het opnieuw; neem contact op met support als dit blijft optreden

Bestandsuploads

Endpoint	Status	Code	Betekenis	Aanbevolen actie
POST /v1/site-files	403	StorageLimitExceeded	De opslagquota van de organisatie is overschreden	Maak opslagruimte vrij of verhoog de quota
POST /v1/site-files	409	FileAlreadyExists	Er bestaat al een bestand met dezelfde identiteit	Gebruik het bestaande bestand, of upload onder een andere naam
POST /v1/site-files/{fileId}/finalize	400	FileNotCompatible	Het formaat van het geüploade bestand is niet compatibel met het verwachte bestandstype	Controleer het bestandsformaat en upload opnieuw
POST /v1/bundles/{bundleId}/upload-sessions	403	StorageLimitExceeded	De opslagquota van de organisatie is overschreden	Maak opslagruimte vrij of verhoog de quota
POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files	403	StorageLimitExceeded	De opslagquota van de organisatie is overschreden	Maak opslagruimte vrij of verhoog de quota
POST /v1/twin/{contextId}/object/attachments	409	StorageLimitExceeded	De opslagquota van de organisatie is overschreden	Maak opslagruimte vrij of verhoog de quota
POST /v1/twin/{contextId}/object/attachments	409	FileAlreadyExists	Er bestaat al een bijlage met dezelfde identiteit	Gebruik de bestaande bijlage, of upload onder een andere naam

Groepen

Groepslidmaatschap

PUT /v1/groups/{groupId}/users/{userId} (lid toevoegen) — 409 Conflict

Code	Betekenis	Aanbevolen actie
GroupHasSamlLink	Het lidmaatschap van de groep wordt beheerd via een SAML/SSO-integratie	Beheer het lidmaatschap via de SAML-provider
CannotInviteToSCIMGroup	Het lidmaatschap van de groep wordt beheerd via SCIM-provisioning	Beheer het lidmaatschap via de SCIM-provider
UserAlreadyMember	De gebruiker is al lid van de groep	Geen actie nodig

DELETE /v1/groups/{groupId}/users/{userId} (lid verwijderen) — 409 Conflict

Code	Betekenis	Aanbevolen actie
GroupHasSamlLink	Het lidmaatschap van de groep wordt beheerd via een SAML/SSO-integratie	Beheer het lidmaatschap via de SAML-provider
CannotRemoveMemberFromSCIMGroup	Het lidmaatschap van de groep wordt beheerd via SCIM-provisioning	Beheer het lidmaatschap via de SCIM-provider

Groepen aanmaken, hernoemen en verwijderen

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

Code	Betekenis	Aanbevolen actie
DuplicateGroupName	Er bestaat al een groep met deze naam in de organisatie	Kies een andere naam
CannotUpdateMemberFromSCIMGroup	Het lidmaatschap van de groep wordt beheerd via SCIM-provisioning	Beheer het lidmaatschap via de SCIM-provider

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

Code	Betekenis	Aanbevolen actie
CannotRemoveSCIMGroup	Het lidmaatschap van de groep wordt beheerd via SCIM-provisioning	Beheer het lidmaatschap via de SCIM-provider
CannotRemoveOrganizationGroup	De groep heeft geen enkele eigenaardivisie	Niet oplosbaar — deze groep kan niet via dit endpoint worden verwijderd

Node- en organisatie-uitnodigingen

POST /v1/nodes/{nodeId}/invitations en POST /v1/invitations gebruiken dezelfde foutcodes.

Status	Code	Betekenis	Aanbevolen actie
409	UserAlreadyInvited	De gebruiker heeft al een openstaande uitnodiging	Geen actie nodig
409	UserAlreadyMember	De gebruiker is al lid	Geen actie nodig
403	InvalidEmailDomain	Het domein van het uitgenodigde e-mailadres is niet toegestaan voor deze organisatie	Gebruik een e-mailadres met een toegestaan domein
400	CustomRoleNotAssignableToDataNode	De opgegeven aangepaste rol kan niet aan deze node worden toegewezen	Kies een rol die aan deze node kan worden toegewezen
400	CustomRoleNotFound	De opgegeven aangepaste rol bestaat niet	Controleer de rol-id
400	AdminsitrativeRoleNotFound*	De opgegeven administratieve rol bestaat niet	Controleer de rol-id
400	AdministrativeRoleInvalidNode	Een administratieve rol was gericht op een node die dit niet ondersteunt	Wijs de administratieve rol toe op organisatieniveau
422	InvitationEmailRejected	De e-mailprovider heeft het adres van de ontvanger permanent afgewezen	Corrigeer het e-mailadres voordat u het opnieuw probeert
503	InvitationEmailNotSent	De e-mailprovider is tijdelijk niet beschikbaar; er is niets opgeslagen	Probeer het verzoek ongewijzigd opnieuw

* Deze codenaam bevat een typefout in de huidige response van de API — gebruik deze exact zoals weergegeven, niet AdministrativeRoleNotFound.

Rate limiting, authenticatie en toegangscontrole

Een 403 kan afkomstig zijn van elk van de drie toegangscontrolelagen die worden beschreven in Aan de slag — Beveiligingsmodel: OAuth-scopes, rollen per node en contenttoegang. Alle drie delen momenteel dezelfde statuscode, en de meeste delen dezelfde generieke body, dus behandel een 403 als “niet geautoriseerd om een van deze redenen” in plaats van er altijd van uit te gaan dat het om een scopeprobleem gaat.

Status	Code	Betekenis
429	rate_limited	De aanvraagbucket van de organisatie is uitgeput — zie Rate Limits
401	not_authenticated	Het verzoek mist een bearer-token, of het token kon niet worden verwerkt
401	invalid_token	De controle van de handtekening of vervaldatum van het token is mislukt
403	(geen code — message: "Insufficient OAuth scopes")	Het token bevat niet de scope die de bewerking vereist — zie OAuth-scopesreferentie
403	(geen code — message: "Forbidden resource")	De rol of contenttoegang van de aanroeper op deze node staat de actie niet toe, of de organisatie heeft een licentie-/gebruikerslimiet bereikt — de body maakt geen onderscheid tussen deze gevallen
403	errorCode: "SSORestrictedResource"	Deze resource is beperkt tot aanroepers die zijn geauthenticeerd via een specifieke SSO-/identiteitsprovider-sessie

Wat is de volgende stap?

• Zie de API-referentie voor volledige verzoek- en responsschema’s per bewerking.