Pular para o conteúdo

Tratamento global de erros no Node.js: respostas e logs

Cada rota trata erro de um jeito, o cliente recebe stack trace e ninguém acha o problema no log. Veja como centralizar o tratamento de erros no Node.js.

Por Roger C. Ribeiro, fundador da Wecodex3 min de leitura

Cada rota trata erro de um jeito, o cliente recebe stack trace e ninguém acha o problema no log. Veja como centralizar o tratamento de erros no Node.js.

Abra cinco rotas do seu backend. Se cada uma tem seu próprio try/catch devolvendo um formato diferente — às vezes { error }, às vezes { message }, às vezes o stack trace inteiro —, o front não sabe o que esperar e o time não sabe o que procurar no log.

Um formato só para todo erro

json
{ "error": { "code": "PEDIDO_NAO_ENCONTRADO", "message": "Pedido não encontrado." } }

Código estável para o front tratar, mensagem que um humano entende. Nada de detalhes internos.

Erros de domínio com significado

ts
export class AppError extends Error {
  constructor(public status: number, public code: string, message: string) { super(message) }
}
export const naoEncontrado = (o: string) => new AppError(404, `${o}_NAO_ENCONTRADO`, `${o} não encontrado.`)

O service lança naoEncontrado('PEDIDO'); não se preocupa com HTTP.

Um middleware no fim da cadeia

ts
app.use((err: unknown, req: Request, res: Response, _next: NextFunction) => {
  if (err instanceof ZodError) return res.status(422).json({ error: { code: 'DADOS_INVALIDOS', message: 'Verifique os campos.', fields: err.flatten().fieldErrors } })
  if (err instanceof AppError) return res.status(err.status).json({ error: { code: err.code, message: err.message } })
  logger.error({ err, path: req.path }, 'erro inesperado')
  res.status(500).json({ error: { code: 'ERRO_INTERNO', message: 'Algo deu errado. Já fomos avisados.' } })
})

Validação (veja Validação de dados com Zod e TypeScript: guia prático), regras de negócio e falhas inesperadas, cada uma com sua resposta.

Nunca vaze o interno

Stack trace, nome de tabela ou mensagem do banco na resposta são mapas para um atacante. O detalhe vai para o log; o cliente recebe só o necessário.

Log que ajuda

Erros inesperados precisam de contexto: rota, usuário, identificador da requisição. Logs estruturados tornam isso pesquisável — veja Logs estruturados: encontre o erro em minutos, não em horas — e sem dados sensíveis (Logs sem dados sensíveis: o vazamento que ninguém percebe).

Esse middleware é a peça final da Arquitetura em camadas no Node.js: Controllers e Services.

Assim são construídos os sistemas web da Wecodex. Fale com a gente.

  • Node.js
  • Erros
  • Express
  • Observabilidade
CompartilharWhatsAppLinkedIn

Escrito por

Roger C. Ribeiro

Fundador da Wecodex. Escreve sobre engenharia de software, performance, APIs, segurança e IA aplicada a empresas.

Serviços relacionados

Resolver de vez, com quem faz isso todo dia

Precisa de uma API ou integração que não caia quando o negócio crescer?

Este artigo mostra o caminho. A implementação sob medida, o detalhe que muda o resultado no seu caso, é o trabalho da Wecodex, empresa de engenharia do grupo Wocom.