> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Modelo de erros

> Consulte a resposta de erro estruturada que as APIs Lerian retornam — códigos, títulos, mensagens e validação de campos — para tratar falhas.

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.

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

## 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

<CodeGroup>
  ```json Campos obrigatórios ausentes theme={null}
  {
    "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"
    }
  }
  ```

  ```json Valores de campo inválidos theme={null}
  {
    "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"
    }
  }
  ```

  ```json Campos inesperados theme={null}
  {
    "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"
    }
  }
  ```
</CodeGroup>

## 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

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