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

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

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

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

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 rigorosa de dados: prevenindo falhas de segurança e dados inconsistentes com Zod e TypeScript), 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: como organizar Controllers, Services e Repositories.

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