Modelo de erros

Para ajudar os parceiros a diagnosticar e resolver problemas rapidamente, todas as APIs retornam uma resposta de erro estruturada. Este modelo é consistente entre endpoints e inclui contexto suficiente para depuração, sem expor detalhes internos.

Estrutura do erro

Toda resposta de erro segue o mesmo formato básico:

{
  "code": "<error_code>",
  "title": "<error_title>",
  "message": "<error_message>"
}

onde

code: Um identificador único e estável para o erro.
title: Um breve resumo do que deu errado.
message: Uma mensagem legível por humanos explicando como corrigir.

Sempre use o campo code para identificar erros programaticamente. Títulos e mensagens podem evoluir para melhorar a clareza.

Erros de validação em nível de campo

Quando um problema está relacionado a campos específicos no payload da requisição, a resposta inclui um objeto fields com informações mais granulares.

Exemplos

{
  "code": "IDE-0009",
  "title": "Missing Fields in Request",
  "message": "Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request.",
  "fields": {
    "document": "document is a required field"
  }
}

{
  "code": "CRM-0047",
  "title": "Bad Request",
  "message": "The server could not understand the request due to malformed syntax. Please check the listed fields and try again.",
  "fields": {
    "legalName": "legalName is a required field.",
    "parentOrganizationId": "parentOrganizationId must be a valid UUID"
  }
}

{
  "code": "CRM-0053",
  "title": "Unexpected Fields in the Request",
  "message": "The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object.",
  "fields": {
    "extraField": "extraField is not allowed"
  }
}

Formato do código de erro

Todos os códigos de erro seguem um formato padronizado para simplificar a depuração e rastreabilidade entre plugins:

<XXX-NNNN>

Onde:

XXX é um prefixo de três letras que identifica o plugin (ex.: IDE para Identity, CRM para CRM).
NNNN é um número de quatro dígitos único para o erro.

Exemplo: IDE-0001 — Campo obrigatório ausente no plugin Identity

Certifique-se de que todos os erros customizados sigam essa estrutura para manter a consistência em todo o ecossistema.

Visão geral

Dicionário de campos

Modelo de erros

Estrutura do erro

Erros de validação em nível de campo

Exemplos

Formato do código de erro

​Estrutura do erro

​Erros de validação em nível de campo

​Exemplos

​Formato do código de erro

Estrutura do erro

Erros de validação em nível de campo

Exemplos

Formato do código de erro