Docs › Backend

Erros

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

GenericError

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:

{
  "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.

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:

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:

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.