Codici di errore

Oltre ai codici di stato HTTP standard, diverse operazioni della RealityConnect API restituiscono nel corpo della risposta un codice error leggibile da un programma, per chiarire il motivo del rifiuto della richiesta. Questa pagina elenca ogni codice denominato per endpoint, cosa lo genera e come gestirlo.

---

Struttura della risposta

Le operazioni che restituiscono un codice denominato usano questa struttura, con campi aggiuntivi specifici per contesto indicati per ciascun endpoint di seguito:

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

message è opzionale e, quando presente, fornisce un dettaglio leggibile da una persona. Basa la logica di gestione su error, non su message.

Gerarchia dei nodi dati

Spostare un nodo

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

Codice	Significato	Azione suggerita
AccessRightsChangeRequired	Lo spostamento cambierebbe chi può accedere al nodo; message illustra la modifica specifica	Verifica la modifica di accesso, oppure riprova con force: true se è accettabile
MaxDepthExceeded	Lo spostamento supererebbe la profondità massima consentita della gerarchia	Sposta il nodo in una posizione meno profonda
CircularityFound	Il genitore di destinazione si trova all’interno del sottoalbero del nodo che si sta spostando	Scegli un genitore esterno al sottoalbero del nodo stesso
NodeHaveMembershipsAttached	Il nodo ha record di appartenenza che ne impediscono lo spostamento oltre un confine di autorizzazione	Rimuovi prima le appartenenze, oppure sposta il nodo all’interno dello stesso ambito di autorizzazione
NodesInDifferentRegions	Il nodo e il genitore di destinazione sono provisionati in region diverse	Non risolvibile: i nodi non possono essere spostati tra region diverse
NodeCannotBeMoved	Questo tipo di nodo non supporta lo spostamento	Non risolvibile per questo tipo di nodo
DerivativesNotInCommonParent	Gli output derivati del nodo non si trovano tutti sotto un genitore comune con la destinazione dello spostamento	Riorganizza i derivati, poi riprova
SourcesNotInCommonParent	Gli input di origine del nodo non si trovano tutti sotto un genitore comune	Riorganizza le origini, poi riprova
DataBundleLinkedToTwin	Il data bundle del nodo è collegato a un twin	Scollega prima il twin
DoesNotMeetHierarchyConstraints	Lo spostamento viola una regola di gerarchia specifica per il tipo	Verifica quali tipi figlio sono consentiti dal genitore di destinazione
MoveNodeFailed	Lo spostamento è stato rifiutato per un motivo senza un codice più specifico	Riprova; contatta il supporto se il problema persiste

Eliminare un nodo

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

Codice	Significato	Azione suggerita
NodeHasDerivatives	Il nodo ha output derivati che devono essere rimossi prima, elencati in derivatives[]	Elimina o sposta i derivati elencati, poi riprova
NodeNotInDeletableState	Il nodo è attualmente in elaborazione oppure l’elaborazione non è riuscita, secondo isProcessing / isFailed	Attendi il termine dell’elaborazione, oppure risolvi il problema, poi riprova
NodeHasBundleDependants	Il data bundle del nodo ha dipendenti che ne impediscono l’eliminazione	Rimuovi prima i dipendenti
DeleteNodeFailed	L’eliminazione è stata rifiutata per un motivo senza un codice più specifico	Riprova; contatta il supporto se il problema persiste

Ripristinare o eliminare definitivamente un nodo nel cestino

Endpoint	Stato	Codice	Significato	Azione suggerita
PATCH /v1/nodes/{id}/restore	409	StorageLimitExceeded	Il ripristino del nodo supererebbe la quota di archiviazione dell’organizzazione	Libera spazio di archiviazione o aumenta la quota, poi riprova
DELETE /v1/nodes/{id}/hard	409	NoNodeRemoved	Il nodo non è stato trovato nel cestino in uno stato rimovibile	Verifica l’id del nodo e il suo stato nel cestino

Elaborazione dei data bundle

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

Codice	Significato	Azione suggerita
ProcessingCostMismatch	Il costo di elaborazione inviato non corrisponde più al costo attuale	Recupera una nuova stima del costo e riprova
NoInputDataFoundForProcessing	Non sono stati trovati dati di input da elaborare per questo bundle	Verifica che la sessione di caricamento sia stata finalizzata prima di avviare l’elaborazione
InsufficientProcessingCapacity	La capacità di elaborazione non è al momento disponibile	Riprova più tardi
FailedToLaunchProcessing	Non è stato possibile avviare il job di elaborazione	Riprova; contatta il supporto se il problema persiste

Caricamento di file

Endpoint	Stato	Codice	Significato	Azione suggerita
POST /v1/site-files	403	StorageLimitExceeded	La quota di archiviazione dell’organizzazione è stata superata	Libera spazio di archiviazione o aumenta la quota
POST /v1/site-files	409	FileAlreadyExists	Esiste già un file con la stessa identità	Usa il file esistente, oppure caricalo con un nome diverso
POST /v1/site-files/{fileId}/finalize	400	FileNotCompatible	Il formato del file caricato non è compatibile con il tipo di file previsto	Verifica il formato del file e ricaricalo
POST /v1/bundles/{bundleId}/upload-sessions	403	StorageLimitExceeded	La quota di archiviazione dell’organizzazione è stata superata	Libera spazio di archiviazione o aumenta la quota
POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files	403	StorageLimitExceeded	La quota di archiviazione dell’organizzazione è stata superata	Libera spazio di archiviazione o aumenta la quota
POST /v1/twin/{contextId}/object/attachments	409	StorageLimitExceeded	La quota di archiviazione dell’organizzazione è stata superata	Libera spazio di archiviazione o aumenta la quota
POST /v1/twin/{contextId}/object/attachments	409	FileAlreadyExists	Esiste già un allegato con la stessa identità	Usa l’allegato esistente, oppure caricalo con un nome diverso

Gruppi

Appartenenza al gruppo

PUT /v1/groups/{groupId}/users/{userId} (aggiungere un membro) — 409 Conflict

Codice	Significato	Azione suggerita
GroupHasSamlLink	L’appartenenza al gruppo è gestita da un’integrazione SAML/SSO	Gestisci l’appartenenza tramite il provider SAML
CannotInviteToSCIMGroup	L’appartenenza al gruppo è gestita tramite il provisioning SCIM	Gestisci l’appartenenza tramite il provider SCIM
UserAlreadyMember	L’utente è già membro del gruppo	Nessuna azione necessaria

DELETE /v1/groups/{groupId}/users/{userId} (rimuovere un membro) — 409 Conflict

Codice	Significato	Azione suggerita
GroupHasSamlLink	L’appartenenza al gruppo è gestita da un’integrazione SAML/SSO	Gestisci l’appartenenza tramite il provider SAML
CannotRemoveMemberFromSCIMGroup	L’appartenenza al gruppo è gestita tramite il provisioning SCIM	Gestisci l’appartenenza tramite il provider SCIM

Creazione, ridenominazione ed eliminazione di gruppi

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

Codice	Significato	Azione suggerita
DuplicateGroupName	Esiste già un gruppo con questo nome nell’organizzazione	Scegli un nome diverso
CannotUpdateMemberFromSCIMGroup	L’appartenenza al gruppo è gestita tramite il provisioning SCIM	Gestisci l’appartenenza tramite il provider SCIM

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

Codice	Significato	Azione suggerita
CannotRemoveSCIMGroup	L’appartenenza al gruppo è gestita tramite il provisioning SCIM	Gestisci l’appartenenza tramite il provider SCIM
CannotRemoveOrganizationGroup	Il gruppo non ha un’unica divisione proprietaria	Non risolvibile: questo gruppo non può essere eliminato tramite questo endpoint

Inviti a nodi e organizzazione

POST /v1/nodes/{nodeId}/invitations e POST /v1/invitations condividono gli stessi codici di errore.

Stato	Codice	Significato	Azione suggerita
409	UserAlreadyInvited	L’utente ha già un invito in sospeso	Nessuna azione necessaria
409	UserAlreadyMember	L’utente è già membro	Nessuna azione necessaria
403	InvalidEmailDomain	Il dominio dell’email invitata non è consentito per questa organizzazione	Usa un indirizzo email con un dominio consentito
400	CustomRoleNotAssignableToDataNode	Il ruolo personalizzato specificato non può essere assegnato a questo nodo	Scegli un ruolo assegnabile a questo nodo
400	CustomRoleNotFound	Il ruolo personalizzato specificato non esiste	Verifica l’id del ruolo
400	AdminsitrativeRoleNotFound*	Il ruolo amministrativo specificato non esiste	Verifica l’id del ruolo
400	AdministrativeRoleInvalidNode	Un ruolo amministrativo è stato applicato a un nodo che non lo supporta	Assegna invece il ruolo amministrativo a livello di organizzazione
422	InvitationEmailRejected	Il provider di posta ha rifiutato in modo permanente l’indirizzo del destinatario	Correggi l’indirizzo email prima di riprovare
503	InvitationEmailNotSent	Il provider di posta non è temporaneamente disponibile; non è stato salvato nulla	Riprova la richiesta senza modifiche

* Il nome di questo codice contiene un errore di battitura nella risposta attuale dell’API: usalo esattamente come mostrato, non AdministrativeRoleNotFound.

Limitazione di frequenza, autenticazione e controllo degli accessi

Un 403 può derivare da uno qualsiasi dei tre livelli di controllo degli accessi descritti in Per iniziare — Modello di sicurezza: scope OAuth, ruoli per nodo e accesso ai contenuti. Attualmente tutti e tre condividono lo stesso codice di stato, e la maggior parte condivide anche lo stesso corpo generico: considera quindi un 403 come “non autorizzato per uno di questi motivi”, piuttosto che presumere che si tratti sempre di un problema di scope.

Stato	Codice	Significato
429	rate_limited	Il bucket di richieste dell’organizzazione è esaurito — consulta Limiti di frequenza
401	not_authenticated	Alla richiesta manca un bearer token, oppure il token non è analizzabile
401	invalid_token	Il controllo della firma o della scadenza del token non è riuscito
403	(nessun codice — messaggio: "Insufficient OAuth scopes")	Il token non include uno scope richiesto dall’operazione — consulta Riferimento agli scope OAuth
403	(nessun codice — messaggio: "Forbidden resource")	Il ruolo o l’accesso ai contenuti del chiamante su questo nodo non consente l’azione, oppure l’organizzazione ha raggiunto un limite di licenze/posti — il corpo della risposta non distingue tra i due casi
403	errorCode: "SSORestrictedResource"	Questa risorsa è riservata ai chiamanti autenticati tramite una sessione SSO/identity provider specifica

Cosa c’è dopo?

• Consulta il riferimento API per gli schemi completi di richiesta e risposta per ogni operazione.