How to Standardize Error Handling with Cursor

1---
2description: Standard error handling for Express routes
3globs: "*.route.ts,*.controller.ts,*.middleware.ts"
4alwaysApply: true
5---
6
7# Error Handling Rules
8- NEVER send raw Error objects or stack traces to clients
9- NEVER use res.status(500).json({ error: err.message }) inline
10- ALWAYS throw custom AppError classes from route handlers
11- ALWAYS let the global error middleware format the response
12- ALWAYS use asyncHandler wrapper for async route handlers
13
14## Standard Error Response Shape:
15```json
16{
17  "success": false,
18  "error": {
19    "code": "VALIDATION_ERROR",
20    "message": "Human-readable error message",
21    "details": []
22  }
23}
24```
25
26## Custom Error Classes:
27- NotFoundError (404)
28- ValidationError (400)
29- UnauthorizedError (401)
30- ForbiddenError (403)
31- ConflictError (409)
32
33Import from @/lib/errors

1export class AppError extends Error {
2  constructor(
3    public statusCode: number,
4    public code: string,
5    message: string,
6    public details?: unknown[]
7  ) {
8    super(message);
9    this.name = 'AppError';
10  }
11}
12
13export class NotFoundError extends AppError {
14  constructor(resource: string, id?: string) {
15    super(404, 'NOT_FOUND', id ? `${resource} with id ${id} not found` : `${resource} not found`);
16  }
17}
18
19export class ValidationError extends AppError {
20  constructor(details: unknown[]) {
21    super(400, 'VALIDATION_ERROR', 'Request validation failed', details);
22  }
23}
24
25export class UnauthorizedError extends AppError {
26  constructor(message = 'Authentication required') {
27    super(401, 'UNAUTHORIZED', message);
28  }
29}
30
31export class ForbiddenError extends AppError {
32  constructor(message = 'Insufficient permissions') {
33    super(403, 'FORBIDDEN', message);
34  }
35}
36
37export class ConflictError extends AppError {
38  constructor(message: string) {
39    super(409, 'CONFLICT', message);
40  }
41}

1import { Request, Response, NextFunction } from 'express';
2import { AppError } from '@/lib/errors';
3import logger from '@/lib/logger';
4
5export const errorHandler = (
6  err: Error,
7  req: Request,
8  res: Response,
9  _next: NextFunction
10): void => {
11  if (err instanceof AppError) {
12    res.status(err.statusCode).json({
13      success: false,
14      error: {
15        code: err.code,
16        message: err.message,
17        details: err.details || [],
18      },
19    });
20    return;
21  }
22
23  logger.error({ err, path: req.path, method: req.method }, 'Unhandled error');
24
25  res.status(500).json({
26    success: false,
27    error: {
28      code: 'INTERNAL_ERROR',
29      message: 'An unexpected error occurred',
30      details: [],
31    },
32  });
33};

1@error-handling.mdc @src/lib/errors.ts @src/middleware/error-handler.ts
2
3Create a products router with these endpoints:
4- GET /api/products — list with pagination
5- GET /api/products/:id — single product (throw NotFoundError if missing)
6- POST /api/products — create (throw ValidationError for bad input)
7- PUT /api/products/:id — update (NotFoundError or ValidationError)
8- DELETE /api/products/:id — delete (NotFoundError if missing)
9
10Use asyncHandler for every route.
11Throw custom error classes from @/lib/errors.
12Do NOT format error responses in route handlers.
13Let the global error middleware handle all error formatting.

1@error-handling.mdc @src/routes/products.route.ts
2
3Generate integration tests for the products API error responses:
41. GET /api/products/nonexistent-id returns 404 with standard error shape
52. POST /api/products with invalid body returns 400 with validation details
63. PUT /api/products/:id with non-existent id returns 404
74. DELETE /api/products/:id with non-existent id returns 404
85. Any 500 error returns generic message, never stack trace
9
10Every error response must match this shape:
11{ success: false, error: { code: string, message: string, details: [] } }
12
13Use supertest for HTTP assertions.