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
{ "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 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
Escrito por
Roger C. RibeiroFundador 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.
Continue lendo
Tudo sobre Backend & APIs- Ler artigo
Backend & APIs3 min
Logs estruturados: encontre o erro em minutos, não em horas
Um cliente reclama de um erro de ontem e o time passa a manhã procurando no meio de milhões de linhas de texto. Logs estruturados resolvem isso.
- Ler artigo
Backend & APIs3 min
Arquitetura em camadas no Node.js: Controllers e Services
Rotas com 400 linhas, regra de negócio misturada com SQL e medo de mexer em qualquer coisa? Veja como organizar um backend Node.js em Controllers, Services e Repositories.
- Ler artigo
Backend & APIs3 min
APIs e integração de sistemas: como integrar sem quebrar
Como fazer integração de sistemas por API sem quebrar: contrato claro, idempotência, rate limit, webhooks e observabilidade.