# Erros

> GenericError, o envelope de erro de domínio e como tratá-lo no frontend sem confundir 404 de proxy com sucesso vazio.

## GenericError

```javascript
const { GenericError } = require("@oondemand/oon-core-back");

throw new GenericError("Informe um nome de até 80 caracteres.", {
  statusCode: 422,
  code: "DEMO_NAME_INVALID",
  details: { field: "nome" },
});
```

O middleware produz o envelope de domínio:

```json
{
  "message": "Informe um nome de até 80 caracteres.",
  "error": {
    "code": "DEMO_NAME_INVALID",
    "message": "Informe um nome de até 80 caracteres.",
    "details": { "field": "nome" },
    "requestId": "correlacao-quando-disponivel"
  }
}
```

`details` e `requestId` são opcionais. Erros comuns com `statusCode` 4xx explícito respondem com esse status (`error.code` é o código do erro ou `HTTP_<status>`), em vez de 500.

> [!WARNING]
> O Core **não** sanitiza arbitrariamente o que o App coloca em `message`/`details`. Normalize erros externos antes de lançá-los — nunca repasse resposta remota, stack, token ou credencial.

## Erros especializados

| Classe | Origem | Status típico |
|---|---|---|
| `DomainRuleError` | Fórmula ou validação declarativa | 422 |
| `DomainManifestError` | `central.domain.json` inválido (`OON_DOMAIN_MANIFEST_INVALID`) | 422 |
| `ProcessManifestError` | `central.process.json` inválido | 422 |
| `AppManifestError` | `central.app.json` inválido | — (boot) |
| `PdfRenderingError` | Capability de PDF (`retryable`) | variável |
| `TransactionalEmailError` | Capability de e-mail (`EMAIL_*`) | variável |

Erros de manifesto carregam `code`, `statusCode` e `issues[]` com `path` e `message`.

## No frontend

O cliente do Core normaliza erros para `OonError`:

```ts
interface OonError { code: string; message: string; status?: number; details?: unknown; requestId?: string }
```

Em chamadas diretas com `useOonApi`, leia `error.response.data.error.message`, com fallback para `data.message` e para o status HTTP:

```tsx
try {
  await http.post("/demo/saudacao", { nome });
} catch (error) {
  const response = (error as { response?: { status?: number; data?: { message?: string; error?: { message?: string } } } }).response;
  setMensagem(response?.data?.error?.message || response?.data?.message || `Falha (HTTP ${response?.status ?? "indisponível"}).`);
}
```

## Regras

- **Faça branching por `code`, nunca pelo texto da mensagem.**
- Respostas legadas e recusas de autenticação podem conter somente `message`.
- Um **404 de proxy/Express pode ser HTML**: investigue rota, proxy ou empacotamento — não é uma rejeição da sua API.
- Não trate erro de rede ou 404 como sucesso vazio.
- Logs e respostas nunca devem conter token, cookie, credencial, senha ou conteúdo sensível.

Lista completa de códigos em [Códigos de erro](/docs/referencia/codigos-de-erro).

Fonte: https://sdk.oonapps.com/docs/backend/erros