Para estruturar um manipulador de erros centralizado (Global Error Handler), o ideal é criar uma classe de erro customizada para erros da aplicação e uma função de middleware para tratar e formatar as respostas.
Abaixo está a implementação completa utilizando Express.js (o padrão também se aplica ao Fastify ou NestJS).
1. Criar uma Classe de Erro Personalizada (AppError.ts)
Essa classe vai padronizar os erros conhecidos da regra de negócio (com status HTTP e mensagens específicas).
2. Middleware Global de Tratamento de Erros (errorHandler.ts)
Este middleware captura as exceções lançadas na aplicação e identifica se a origem foi o Zod, o Prisma ou a própria aplicação.
3. Aplicando no Servidor Express (app.ts)
O middleware de erro deve ser o último registrado no servidor (após todas as rotas).
Respostas de Exemplo Retornadas pela API
# 🛡️ Manipulador de Erros Centralizado – Versão Aprimorada
Baseado no seu arquivo, desenvolvi uma **solução completa e expansível** para tratamento de erros em APIs Node.js, com suporte a **Zod, Prisma, logs estruturados, rastreamento e múltiplos frameworks**.
---
## 📦 Estrutura de Pastas Sugerida
```
src/
├── errors/
│ ├── AppError.ts
│ ├── ErrorTypes.ts
│ └── errorHandler.ts
├── middlewares/
│ └── errorHandler.ts (pode ser único)
├── utils/
│ └── logger.ts
└── app.ts
```
---
## 1️⃣ Classe de Erro Customizada (`AppError.ts`)
Com suporte a **códigos de erro** e **detalhes adicionais**.
```typescript
export class AppError extends Error {
public readonly statusCode: number;
public readonly errorCode?: string;
public readonly details?: any;
constructor(
message: string,
statusCode: number = 400,
errorCode?: string,
details?: any
) {
super(message);
this.name = this.constructor.name;
this.statusCode = statusCode;
this.errorCode = errorCode;
this.details = details;
Error.captureStackTrace(this, this.constructor);
}
}
// Erros específicos podem herdar
export class NotFoundError extends AppError {
constructor(message: string = 'Recurso não encontrado') {
super(message, 404, 'NOT_FOUND');
}
}
export class UnauthorizedError extends AppError {
constructor(message: string = 'Não autorizado') {
super(message, 401, 'UNAUTHORIZED');
}
}
export class ConflictError extends AppError {
constructor(message: string = 'Conflito de dados') {
super(message, 409, 'CONFLICT');
}
}
export class ValidationError extends AppError {
constructor(message: string = 'Dados inválidos', details?: any) {
super(message, 400, 'VALIDATION_ERROR', details);
}
}
```
---
## 2️⃣ Middleware Global de Erros (`errorHandler.ts`)
Com tratamento para **Zod, Prisma, JWT, Multer, Axios** e erros inesperados.
```typescript
import { Request, Response, NextFunction, ErrorRequestHandler } from 'express';
import { ZodError } from 'zod';
import { Prisma } from '@prisma/client';
import { JsonWebTokenError, TokenExpiredError } from 'jsonwebtoken';
import { MulterError } from 'multer';
import { AppError } from './AppError';
import logger from '../utils/logger';
// Função para formatar erros do Zod de forma amigável
function formatZodError(error: ZodError) {
const errors: Record<string, string[]> = {};
error.errors.forEach((err) => {
const path = err.path.join('.');
if (!errors[path]) errors[path] = [];
errors[path].push(err.message);
});
return errors;
}
export const errorHandler: ErrorRequestHandler = (
error: Error,
req: Request,
res: Response,
next: NextFunction
): void => {
// Log do erro (com informações de requisição)
logger.error({
message: error.message,
stack: error.stack,
method: req.method,
url: req.url,
ip: req.ip,
body: req.body,
query: req.query,
params: req.params,
user: (req as any).user?.id,
});
// ---- 1. Erro de Validação (Zod) ----
if (error instanceof ZodError) {
res.status(400).json({
status: 'validation_error',
message: 'Dados de entrada inválidos.',
errors: formatZodError(error),
});
return;
}
// ---- 2. Erros do Prisma ----
if (error instanceof Prisma.PrismaClientKnownRequestError) {
const meta = error.meta as any;
// P2002 – Chave única duplicada
if (error.code === 'P2002') {
const fields = meta?.target?.join(', ') || 'campo desconhecido';
res.status(409).json({
status: 'conflict_error',
message: `Já existe um registro com este valor para: ${fields}.`,
field: meta?.target?.[0],
});
return;
}
// P2025 – Registro não encontrado
if (error.code === 'P2025') {
res.status(404).json({
status: 'not_found',
message: 'Registro não encontrado.',
});
return;
}
// P2003 – Chave estrangeira violada
if (error.code === 'P2003') {
res.status(400).json({
status: 'foreign_key_error',
message: 'Operação viola integridade referencial.',
field: meta?.field_name,
});
return;
}
// P2000 – Valor muito longo
if (error.code === 'P2000') {
res.status(400).json({
status: 'invalid_data',
message: 'O valor fornecido excede o tamanho permitido.',
field: meta?.column,
});
return;
}
// Outros erros do Prisma (tratamento genérico)
res.status(500).json({
status: 'database_error',
message: 'Erro ao processar a operação no banco de dados.',
code: error.code,
});
return;
}
// ---- 3. Erros JWT (autenticação) ----
if (error instanceof JsonWebTokenError) {
res.status(401).json({
status: 'auth_error',
message: 'Token inválido.',
});
return;
}
if (error instanceof TokenExpiredError) {
res.status(401).json({
status: 'auth_error',
message: 'Token expirado.',
});
return;
}
// ---- 4. Erros do Multer (upload) ----
if (error instanceof MulterError) {
const messages: Record<string, string> = {
LIMIT_FILE_SIZE: 'Arquivo excede o tamanho máximo permitido.',
LIMIT_FILE_COUNT: 'Número máximo de arquivos excedido.',
LIMIT_UNEXPECTED_FILE: 'Campo de arquivo inesperado.',
};
res.status(400).json({
status: 'upload_error',
message: messages[error.code] || 'Erro no upload do arquivo.',
code: error.code,
});
return;
}
// ---- 5. Erros da Aplicação (AppError) ----
if (error instanceof AppError) {
res.status(error.statusCode).json({
status: 'error',
message: error.message,
code: error.errorCode,
details: error.details,
});
return;
}
// ---- 6. Erros de Rate Limiting (se usar express-rate-limit) ----
if ((error as any).code === 'LIMIT_RATE') {
res.status(429).json({
status: 'too_many_requests',
message: 'Muitas requisições. Tente novamente mais tarde.',
});
return;
}
// ---- 7. Erros Inesperados (fallback) ----
// Em produção, não enviamos stack trace
const isProduction = process.env.NODE_ENV === 'production';
res.status(500).json({
status: 'internal_error',
message: isProduction
? 'Ocorreu um erro interno no servidor.'
: error.message,
...(isProduction ? {} : { stack: error.stack }),
});
};
```
---
## 3️⃣ Logger Estruturado (`logger.ts`)
Usando **Pino** para logs JSON (recomendado) ou **Winston**.
```typescript
import pino from 'pino';
const isProduction = process.env.NODE_ENV === 'production';
export const logger = pino({
level: process.env.LOG_LEVEL || 'info',
transport: isProduction
? undefined
: {
target: 'pino-pretty',
options: {
colorize: true,
translateTime: 'SYS:standard',
ignore: 'pid,hostname',
},
},
redact: ['req.headers.authorization', 'req.body.password', 'req.body.token'],
});
export default logger;
```
---
## 4️⃣ Aplicação no Express (`app.ts`)
```typescript
import express from 'express';
import 'express-async-errors';
import { errorHandler } from './middlewares/errorHandler';
import { AppError, NotFoundError, ConflictError } from './errors/AppError';
import { prisma } from './prisma';
import { z } from 'zod';
const app = express();
app.use(express.json());
// ---- Rotas ----
const UserSchema = z.object({
name: z.string().min(3, 'Nome deve ter no mínimo 3 caracteres'),
email: z.string().email('E-mail inválido'),
password: z.string().min(6, 'Senha deve ter no mínimo 6 caracteres'),
});
app.post('/users', async (req, res) => {
const data = UserSchema.parse(req.body);
const existing = await prisma.user.findUnique({
where: { email: data.email },
});
if (existing) {
throw new ConflictError('E-mail já cadastrado.');
}
// Simula criação (hash senha, etc)
const user = await prisma.user.create({
data: {
name: data.name,
email: data.email,
password: 'hashed_password', // hash real
},
});
res.status(201).json(user);
});
app.get('/users/:id', async (req, res) => {
const user = await prisma.user.findUnique({
where: { id: req.params.id },
});
if (!user) {
throw new NotFoundError('Usuário não encontrado.');
}
res.json(user);
});
// Rota que lança erro genérico para teste
app.get('/error', () => {
throw new Error('Erro inesperado!');
});
// ---- Middleware de Erros (SEMPRE por último) ----
app.use(errorHandler);
app.listen(3000, () => console.log('🚀 Server running on port 3000'));
```
---
## 5️⃣ Para Fastify
Se estiver usando **Fastify**, a adaptação é simples:
```typescript
import fastify from 'fastify';
import { ZodError } from 'zod';
import { AppError } from './AppError';
const app = fastify();
app.setErrorHandler((error, request, reply) => {
if (error instanceof ZodError) {
return reply.status(400).send({
status: 'validation_error',
message: 'Dados inválidos',
errors: error.flatten().fieldErrors,
});
}
if (error instanceof AppError) {
return reply.status(error.statusCode).send({
status: 'error',
message: error.message,
});
}
// Log do erro
request.log.error(error);
return reply.status(500).send({
status: 'internal_error',
message: 'Erro interno do servidor.',
});
});
```
---
## 6️⃣ Para NestJS
No NestJS, use **filtros de exceção globais**:
```typescript
// exception.filter.ts
import {
ExceptionFilter,
Catch,
ArgumentsHost,
HttpException,
HttpStatus,
} from '@nestjs/common';
import { ZodError } from 'zod';
import { AppError } from './AppError';
@Catch()
export class GlobalExceptionFilter implements ExceptionFilter {
catch(exception: unknown, host: ArgumentsHost) {
const ctx = host.switchToHttp();
const response = ctx.getResponse();
let status = HttpStatus.INTERNAL_SERVER_ERROR;
let message = 'Erro interno do servidor.';
let errors = undefined;
if (exception instanceof ZodError) {
status = HttpStatus.BAD_REQUEST;
message = 'Dados inválidos';
errors = exception.flatten().fieldErrors;
} else if (exception instanceof AppError) {
status = exception.statusCode;
message = exception.message;
} else if (exception instanceof HttpException) {
status = exception.getStatus();
message = exception.message;
}
response.status(status).json({
statusCode: status,
message,
errors,
timestamp: new Date().toISOString(),
});
}
}
```
E no módulo principal:
```typescript
app.useGlobalFilters(new GlobalExceptionFilter());
```
---
## 7️⃣ Teste Unitário do Error Handler (exemplo com Jest)
```typescript
import { errorHandler } from './errorHandler';
import { AppError } from './AppError';
import { ZodError } from 'zod';
describe('errorHandler', () => {
let req: any, res: any, next: any;
beforeEach(() => {
req = { method: 'GET', url: '/test', ip: '127.0.0.1' };
res = { status: jest.fn().mockReturnThis(), json: jest.fn() };
next = jest.fn();
});
it('deve tratar AppError corretamente', () => {
const error = new AppError('Mensagem de erro', 403);
errorHandler(error, req, res, next);
expect(res.status).toHaveBeenCalledWith(403);
expect(res.json).toHaveBeenCalledWith({
status: 'error',
message: 'Mensagem de erro',
code: undefined,
details: undefined,
});
});
it('deve tratar ZodError corretamente', () => {
const error = new ZodError([
{ path: ['email'], message: 'E-mail inválido', code: 'invalid_string' },
]);
errorHandler(error, req, res, next);
expect(res.status).toHaveBeenCalledWith(400);
expect(res.json).toHaveBeenCalledWith({
status: 'validation_error',
message: 'Dados de entrada inválidos.',
errors: { email: ['E-mail inválido'] },
});
});
});
```
---
## 🎯 Resumo do Fluxo
1. **Camada de Serviço/Controller** lança `AppError` com status e mensagem.
2. **Middleware Global** captura todos os erros.
3. Identifica a origem (Zod, Prisma, JWT, Multer, AppError, etc.).
4. Formata a resposta de forma consistente para o cliente.
5. **Loga** o erro com detalhes para monitoramento.
6. Em produção, **não expõe** stack trace.
---
## ✅ Benefícios
- **Centralização** – um único ponto para gerenciar todos os erros.
- **Consistência** – todas as respostas de erro seguem o mesmo padrão.
- **Segurança** – não vazamos detalhes internos em produção.
- **Rastreabilidade** – logs estruturados facilitam a depuração.
- **Extensibilidade** – fácil adicionar novos tipos de erro.
---
Quer que eu adicione suporte a **Sentry**, **Slack notifications** ou **tratamento de erros assíncronos com **`try/catch`** em rotas específicas? Posso expandir! 🚀
