Códigos de erro

Além dos códigos de status HTTP padrão, várias operações da RealityConnect API retornam um código error legível por máquina no corpo da resposta para esclarecer por que uma requisição foi rejeitada. Esta página cataloga todos os códigos nomeados por endpoint, o que os aciona e como tratá-los.

Formato da resposta

As operações que retornam um código nomeado usam este formato, com campos adicionais específicos de cada endpoint indicados abaixo:

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

message é opcional e, quando presente, traz um detalhe legível por humanos. Baseie o tratamento em error, não em message.

Hierarquia de nós de dados

Mover um nó

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

Código	Significado	Ação sugerida
`AccessRightsChangeRequired`	A movimentação mudaria quem pode acessar o nó; `message` explica a mudança específica	Revise a mudança de acesso ou tente novamente com `force: true` se for aceitável
`MaxDepthExceeded`	A movimentação excederia a profundidade máxima permitida da hierarquia	Mova o nó para um local menos profundo
`CircularityFound`	O nó pai de destino está dentro da subárvore do nó que está sendo movido	Escolha um pai fora da própria subárvore do nó
`NodeHaveMembershipsAttached`	O nó tem registros de membership que impedem movê-lo entre limites de permissão	Remova os memberships primeiro, ou mova dentro do mesmo escopo de permissão
`NodesInDifferentRegions`	O nó e o pai de destino estão provisionados em regiões diferentes	Não é possível resolver — nós não podem ser movidos entre regiões
`NodeCannotBeMoved`	Este tipo de nó não suporta movimentação	Não é possível resolver para este tipo de nó
`DerivativesNotInCommonParent`	As saídas derivadas do nó não estão todas sob um pai comum com o destino da movimentação	Reorganize as derivadas e tente novamente
`SourcesNotInCommonParent`	As entradas de origem do nó não estão todas sob um pai comum	Reorganize as origens e tente novamente
`DataBundleLinkedToTwin`	O data bundle do nó está vinculado a um twin	Desvincule o twin primeiro
`DoesNotMeetHierarchyConstraints`	A movimentação viola uma regra de hierarquia específica do tipo	Verifique quais tipos filhos o pai de destino permite
`MoveNodeFailed`	A movimentação foi rejeitada por um motivo sem código mais específico	Tente novamente; contate o suporte se persistir

Excluir um nó

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

Código	Significado	Ação sugerida
`NodeHasDerivatives`	O nó tem saídas derivadas que precisam ser removidas primeiro, listadas em `derivatives[]`	Exclua ou mova as derivadas listadas e tente novamente
`NodeNotInDeletableState`	O nó está processando ou falhou no processamento, conforme `isProcessing` / `isFailed`	Aguarde o processamento terminar, ou resolva a falha, e tente novamente
`NodeHasBundleDependants`	O data bundle do nó tem dependentes que impedem a exclusão	Remova os dependentes primeiro
`DeleteNodeFailed`	A exclusão foi rejeitada por um motivo sem código mais específico	Tente novamente; contate o suporte se persistir

Restaurar ou excluir definitivamente um nó da lixeira

Endpoint	Status	Código	Significado	Ação sugerida
`PATCH /v1/nodes/{id}/restore`	409	`StorageLimitExceeded`	Restaurar o nó excederia a cota de armazenamento da organização	Libere espaço de armazenamento ou aumente a cota e tente novamente
`DELETE /v1/nodes/{id}/hard`	409	`NoNodeRemoved`	O nó não foi encontrado na lixeira em um estado removível	Verifique o id do nó e seu estado na lixeira

Processamento de data bundle

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

Código	Significado	Ação sugerida
`ProcessingCostMismatch`	O custo de processamento enviado não corresponde mais ao custo atual	Busque uma nova estimativa de custo e tente novamente
`NoInputDataFoundForProcessing`	Nenhum dado de entrada foi encontrado para processar este bundle	Verifique se a sessão de upload foi finalizada antes de acionar o processamento
`InsufficientProcessingCapacity`	Não há capacidade de processamento disponível no momento	Tente novamente mais tarde
`FailedToLaunchProcessing`	O job de processamento não pôde ser iniciado	Tente novamente; contate o suporte se persistir

Uploads de arquivo

Endpoint	Status	Código	Significado	Ação sugerida
`POST /v1/site-files`	403	`StorageLimitExceeded`	A cota de armazenamento da organização foi excedida	Libere espaço de armazenamento ou aumente a cota
`POST /v1/site-files`	409	`FileAlreadyExists`	Já existe um arquivo com a mesma identidade	Use o arquivo existente ou envie com um nome diferente
`POST /v1/site-files/{fileId}/finalize`	400	`FileNotCompatible`	O formato do arquivo enviado não é compatível com o tipo de arquivo esperado	Verifique o formato do arquivo e envie novamente
`POST /v1/bundles/{bundleId}/upload-sessions`	403	`StorageLimitExceeded`	A cota de armazenamento da organização foi excedida	Libere espaço de armazenamento ou aumente a cota
`POST /v1/bundles/{bundleId}/upload-sessions/{sessionId}/files`	403	`StorageLimitExceeded`	A cota de armazenamento da organização foi excedida	Libere espaço de armazenamento ou aumente a cota
`POST /v1/twin/{contextId}/object/attachments`	409	`StorageLimitExceeded`	A cota de armazenamento da organização foi excedida	Libere espaço de armazenamento ou aumente a cota
`POST /v1/twin/{contextId}/object/attachments`	409	`FileAlreadyExists`	Já existe um anexo com a mesma identidade	Use o anexo existente ou envie com um nome diferente

Grupos

Membership de grupo

PUT /v1/groups/{groupId}/users/{userId} (adicionar um membro) — 409 Conflict

Código	Significado	Ação sugerida
`GroupHasSamlLink`	O membership do grupo é gerenciado por uma integração SAML/SSO	Gerencie o membership pelo provedor SAML
`CannotInviteToSCIMGroup`	O membership do grupo é gerenciado por provisionamento SCIM	Gerencie o membership pelo provedor SCIM
`UserAlreadyMember`	O usuário já é membro do grupo	Nenhuma ação necessária

DELETE /v1/groups/{groupId}/users/{userId} (remover um membro) — 409 Conflict

Código	Significado	Ação sugerida
`GroupHasSamlLink`	O membership do grupo é gerenciado por uma integração SAML/SSO	Gerencie o membership pelo provedor SAML
`CannotRemoveMemberFromSCIMGroup`	O membership do grupo é gerenciado por provisionamento SCIM	Gerencie o membership pelo provedor SCIM

Criar, renomear e excluir grupos

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

Código	Significado	Ação sugerida
`DuplicateGroupName`	Já existe um grupo com este nome na organização	Escolha um nome diferente
`CannotUpdateMemberFromSCIMGroup`	O membership do grupo é gerenciado por provisionamento SCIM	Gerencie o membership pelo provedor SCIM

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

Código	Significado	Ação sugerida
`CannotRemoveSCIMGroup`	O membership do grupo é gerenciado por provisionamento SCIM	Gerencie o membership pelo provedor SCIM
`CannotRemoveOrganizationGroup`	O grupo não tem uma única divisão proprietária	Não é possível resolver — este grupo não pode ser excluído por este endpoint

Convites de nó e organização

POST /v1/nodes/{nodeId}/invitations e POST /v1/invitations compartilham os mesmos códigos de erro.

Status	Código	Significado	Ação sugerida
409	`UserAlreadyInvited`	O usuário já tem um convite pendente	Nenhuma ação necessária
409	`UserAlreadyMember`	O usuário já é membro	Nenhuma ação necessária
403	`InvalidEmailDomain`	O domínio do e-mail convidado não é permitido para esta organização	Use um endereço de e-mail em um domínio permitido
400	`CustomRoleNotAssignableToDataNode`	A função personalizada especificada não pode ser atribuída a este nó	Escolha uma função atribuível a este nó
400	`CustomRoleNotFound`	A função personalizada especificada não existe	Verifique o id da função
400	`AdminsitrativeRoleNotFound`*	A função administrativa especificada não existe	Verifique o id da função
400	`AdministrativeRoleInvalidNode`	Uma função administrativa foi direcionada a um nó que não a suporta	Atribua a função administrativa no nível da organização
422	`InvitationEmailRejected`	O provedor de e-mail rejeitou permanentemente o endereço do destinatário	Corrija o endereço de e-mail antes de tentar novamente
503	`InvitationEmailNotSent`	O provedor de e-mail está temporariamente indisponível; nada foi persistido	Tente novamente a requisição como está

* Este nome de código traz um erro de digitação na resposta atual da API — use-o exatamente como mostrado, não AdministrativeRoleNotFound.

Limite de taxa, autenticação e controle de acesso

Um 403 pode vir de qualquer uma das três camadas de controle de acesso descritas em Primeiros passos — Modelo de segurança: escopos OAuth, funções por nó e acesso a conteúdo. As três atualmente compartilham o mesmo código de status, e a maioria compartilha o mesmo corpo genérico, então trate um 403 como “não autorizado por um destes motivos” em vez de assumir que é sempre um problema de escopo.

Status	Código	Significado
429	`rate_limited`	O bucket de requisições da organização está esgotado — veja Limites de taxa
401	`not_authenticated`	A requisição não tem um bearer token, ou o token não pôde ser interpretado
401	`invalid_token`	A verificação de assinatura ou expiração do token falhou
403	(sem código — mensagem: `"Insufficient OAuth scopes"`)	O token não tem um escopo que a operação exige — veja Escopos OAuth
403	(sem código — mensagem: `"Forbidden resource"`)	A função ou o acesso a conteúdo do chamador neste nó não permite a ação, ou a organização atingiu um limite de licenciamento/vagas — o corpo não distingue qual dos dois
403	`errorCode: "SSORestrictedResource"`	Este recurso é restrito a chamadores autenticados por uma sessão específica de SSO/provedor de identidade

Próximos passos

Consulte a referência da API para os esquemas completos de requisição e resposta de cada operação.