Codes d'erreur

Au-delà des codes de statut HTTP standards, plusieurs opérations de la RealityConnect API renvoient un code error exploitable par programme dans le corps de la réponse pour préciser la raison du rejet de la requête. Cette page recense chaque code nommé par endpoint, ce qui le déclenche, et comment le gérer.

---

Forme de la réponse

Les opérations qui renvoient un code nommé utilisent cette forme, avec des champs supplémentaires propres à chaque endpoint, indiqués ci-dessous :

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

message est optionnel et, lorsqu’il est présent, donne un détail lisible par un humain. Basez votre traitement sur error, pas sur message.

Hiérarchie des nœuds de données

Déplacer un nœud

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

Code	Signification	Action suggérée
AccessRightsChangeRequired	Le déplacement changerait qui peut accéder au nœud ; message explique le changement précis	Examinez le changement d’accès, ou retentez avec force: true si cela est acceptable
MaxDepthExceeded	Le déplacement dépasserait la profondeur de hiérarchie maximale autorisée	Déplacez le nœud vers un emplacement moins profond
CircularityFound	Le parent cible se trouve dans la sous-arborescence du nœud déplacé	Choisissez un parent hors de la sous-arborescence du nœud
NodeHaveMembershipsAttached	Le nœud a des enregistrements d’appartenance qui bloquent son déplacement au-delà d’une frontière de permission	Retirez d’abord les appartenances, ou déplacez le nœud dans la même portée de permission
NodesInDifferentRegions	Le nœud et le parent cible sont provisionnés dans des régions différentes	Non résoluble — les nœuds ne peuvent pas être déplacés entre régions
NodeCannotBeMoved	Ce type de nœud ne prend pas en charge le déplacement	Non résoluble pour ce type de nœud
DerivativesNotInCommonParent	Les sorties dérivées du nœud ne sont pas toutes sous un parent commun avec la cible du déplacement	Réorganisez les dérivés, puis retentez
SourcesNotInCommonParent	Les entrées source du nœud ne sont pas toutes sous un parent commun	Réorganisez les sources, puis retentez
DataBundleLinkedToTwin	Le data bundle du nœud est lié à un twin	Détachez d’abord le twin
DoesNotMeetHierarchyConstraints	Le déplacement viole une règle de hiérarchie propre au type	Vérifiez quels types enfants le parent cible autorise
MoveNodeFailed	Le déplacement a été rejeté pour une raison sans code plus précis	Retentez ; contactez le support si cela persiste

Supprimer un nœud

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

Code	Signification	Action suggérée
NodeHasDerivatives	Le nœud a des sorties dérivées qui doivent d’abord être supprimées, listées dans derivatives[]	Supprimez ou déplacez les dérivés listés, puis retentez
NodeNotInDeletableState	Le nœud est en cours de traitement ou son traitement a échoué, voir isProcessing / isFailed	Attendez la fin du traitement, ou résolvez l’échec, puis retentez
NodeHasBundleDependants	Le data bundle du nœud a des dépendants qui bloquent la suppression	Retirez d’abord les dépendants
DeleteNodeFailed	La suppression a été rejetée pour une raison sans code plus précis	Retentez ; contactez le support si cela persiste

Restaurer ou supprimer définitivement un nœud dans la corbeille

Endpoint	Statut	Code	Signification	Action suggérée
PATCH /v1/nodes/{id}/restore	409	StorageLimitExceeded	Restaurer le nœud dépasserait le quota de stockage de l’organisation	Libérez du stockage ou augmentez le quota, puis retentez
DELETE /v1/nodes/{id}/hard	409	NoNodeRemoved	Le nœud n’a pas été trouvé dans la corbeille dans un état supprimable	Vérifiez l’id du nœud et son état dans la corbeille

Traitement des data bundles

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

Code	Signification	Action suggérée
ProcessingCostMismatch	Le coût de traitement soumis ne correspond plus au coût actuel	Récupérez une nouvelle estimation de coût et retentez
NoInputDataFoundForProcessing	Aucune donnée d’entrée n’a été trouvée pour traiter ce bundle	Vérifiez que la session d’upload a été finalisée avant de déclencher le traitement
InsufficientProcessingCapacity	La capacité de traitement n’est actuellement pas disponible	Retentez plus tard
FailedToLaunchProcessing	Le job de traitement n’a pas pu être lancé	Retentez ; contactez le support si cela persiste

Uploads de fichiers

Endpoint	Statut	Code	Signification	Action suggérée
POST /v1/site-files	403	StorageLimitExceeded	Le quota de stockage de l’organisation est dépassé	Libérez du stockage ou augmentez le quota
POST /v1/site-files	409	FileAlreadyExists	Un fichier avec la même identité existe déjà	Utilisez le fichier existant, ou uploadez sous un autre nom
POST /v1/site-files/{fileId}/finalize	400	FileNotCompatible	Le format du fichier uploadé n’est pas compatible avec le type de fichier attendu	Vérifiez le format du fichier et re-uploadez
POST /v1/bundles/{bundleId}/upload-sessions	403	StorageLimitExceeded	Le quota de stockage de l’organisation est dépassé	Libérez du stockage ou augmentez le quota
POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files	403	StorageLimitExceeded	Le quota de stockage de l’organisation est dépassé	Libérez du stockage ou augmentez le quota
POST /v1/twin/{contextId}/object/attachments	409	StorageLimitExceeded	Le quota de stockage de l’organisation est dépassé	Libérez du stockage ou augmentez le quota
POST /v1/twin/{contextId}/object/attachments	409	FileAlreadyExists	Une pièce jointe avec la même identité existe déjà	Utilisez la pièce jointe existante, ou uploadez sous un autre nom

Groupes

Appartenance à un groupe

PUT /v1/groups/{groupId}/users/{userId} (ajouter un membre) — 409 Conflict

Code	Signification	Action suggérée
GroupHasSamlLink	L’appartenance au groupe est gérée par une intégration SAML/SSO	Gérez l’appartenance via le fournisseur SAML
CannotInviteToSCIMGroup	L’appartenance au groupe est gérée par provisionnement SCIM	Gérez l’appartenance via le fournisseur SCIM
UserAlreadyMember	L’utilisateur est déjà membre du groupe	Aucune action requise

DELETE /v1/groups/{groupId}/users/{userId} (retirer un membre) — 409 Conflict

Code	Signification	Action suggérée
GroupHasSamlLink	L’appartenance au groupe est gérée par une intégration SAML/SSO	Gérez l’appartenance via le fournisseur SAML
CannotRemoveMemberFromSCIMGroup	L’appartenance au groupe est gérée par provisionnement SCIM	Gérez l’appartenance via le fournisseur SCIM

Créer, renommer et supprimer des groupes

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

Code	Signification	Action suggérée
DuplicateGroupName	Un groupe portant ce nom existe déjà dans l’organisation	Choisissez un autre nom
CannotUpdateMemberFromSCIMGroup	L’appartenance au groupe est gérée par provisionnement SCIM	Gérez l’appartenance via le fournisseur SCIM

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

Code	Signification	Action suggérée
CannotRemoveSCIMGroup	L’appartenance au groupe est gérée par provisionnement SCIM	Gérez l’appartenance via le fournisseur SCIM
CannotRemoveOrganizationGroup	Le groupe n’a pas de division propriétaire unique	Non résoluble — ce groupe ne peut pas être supprimé via cet endpoint

Invitations de nœud et d’organisation

POST /v1/nodes/{nodeId}/invitations et POST /v1/invitations partagent les mêmes codes d’erreur.

Statut	Code	Signification	Action suggérée
409	UserAlreadyInvited	L’utilisateur a déjà une invitation en attente	Aucune action requise
409	UserAlreadyMember	L’utilisateur est déjà membre	Aucune action requise
403	InvalidEmailDomain	Le domaine de l’email invité n’est pas autorisé pour cette organisation	Utilisez une adresse email sur un domaine autorisé
400	CustomRoleNotAssignableToDataNode	Le rôle personnalisé indiqué ne peut pas être attribué à ce nœud	Choisissez un rôle attribuable à ce nœud
400	CustomRoleNotFound	Le rôle personnalisé indiqué n’existe pas	Vérifiez l’id du rôle
400	AdminsitrativeRoleNotFound*	Le rôle administratif indiqué n’existe pas	Vérifiez l’id du rôle
400	AdministrativeRoleInvalidNode	Un rôle administratif a été ciblé sur un nœud qui ne le prend pas en charge	Attribuez le rôle administratif au niveau de l’organisation
422	InvitationEmailRejected	Le fournisseur de messagerie a rejeté définitivement l’adresse du destinataire	Corrigez l’adresse email avant de retenter
503	InvitationEmailNotSent	Le fournisseur de messagerie est temporairement indisponible ; rien n’a été persisté	Retentez la requête telle quelle

* Ce nom de code contient une faute de frappe dans la réponse actuelle de l’API — reproduisez-le exactement tel qu’indiqué, pas AdministrativeRoleNotFound.

Limitation de débit, authentification et contrôle d’accès

Un 403 peut provenir de n’importe laquelle des trois couches de contrôle d’accès décrites dans Getting Started — Modèle de sécurité : les scopes OAuth, les rôles par nœud, et l’accès au contenu. Les trois partagent actuellement le même code de statut, et la plupart partagent le même corps générique ; traitez donc un 403 comme « non autorisé pour une de ces raisons » plutôt que de supposer qu’il s’agit toujours d’un problème de scope.

Statut	Code	Signification
429	rate_limited	Le bucket de requêtes de l’organisation est épuisé — voir Limites de débit
401	not_authenticated	La requête n’a pas de jeton bearer, ou le jeton n’a pas pu être analysé
401	invalid_token	La vérification de signature ou d’expiration du jeton a échoué
403	(pas de code — message : "Insufficient OAuth scopes")	Le jeton ne porte pas un scope requis par l’opération — voir Scopes OAuth
403	(pas de code — message : "Forbidden resource")	Le rôle ou l’accès au contenu de l’appelant sur ce nœud ne permet pas l’action, ou l’organisation a atteint une limite de licences/sièges — le corps ne permet pas de distinguer laquelle
403	errorCode: "SSORestrictedResource"	Cette ressource est restreinte aux appelants authentifiés via une session SSO/fournisseur d’identité spécifique

Et ensuite ?

• Consultez la référence API pour les schémas complets de requête et de réponse par opération.