NestJS Error Handling Standards
Priority: P1 (OPERATIONAL)
- Requirement: Centralize error formatting.
- Platform Agnostic: not import
Request/Response from Express/Fastify types directly.
- Use:
HttpAdapterHost to access underlying platform response methods.
const { httpAdapter } = this.httpAdapterHost;- Structure:
- Implement strictly typed error responses.
- Refer to API Standards for
ApiErrorResponse.
{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request",
"timestamp": "ISO...",
"path": "/users"
}
Error Flow
- Service: Throws specific or generic errors (e.g.,
EntityNotFoundError).
- Interceptor: Maps low-level errors to HTTP Exceptions (e.g.,
catchError(err => throw new NotFoundException())).
- Why: Keeps Exception Filters focused on formatting, not business logic interpretation.
- Global Filter: Formats final JSON response.
Built-in Exceptions
- Use: Throw
NotFoundException, ForbiddenException, BadRequestException.
- Custom: Extend
HttpException only for domain-specific failures that need specific status codes.
Logging
- Context: Always pass
MyClass.name to Logger constructor.
- Levels:
error: 500s (Stack trace required).warn: 400s (Client errors).
Security (Information Leakage)
- Production: NEVER expose stack traces in HTTP responses (
process.env.NODE_ENV === 'production').
- Sanitization: Ensure
ApiException payloads not leak internal file paths or raw variable dumps.
Anti-Patterns
- No stack traces in production: Gate stack exposure behind
NODE_ENV === 'production' check.
- No Express types in filters: Use
HttpAdapterHost for platform-agnostic error handling.
- No HttpException in services: Throw domain errors in services; let Interceptors map to HTTP exceptions.
