Error Handling

Hierarchy

PyqDeck uses a custom error hierarchy based on a BaseError class to ensure all errors have a consistent structure and status code.

Located in backend/src/utils/errors/index.js:

Class	HTTP Code	Purpose
`ValidationError`	400	Invalid input data or Zod validation failure.
`UnauthorizedError`	401	Missing or invalid authentication token.
`ForbiddenError`	403	Authenticated user lacks required permissions.
`NotFoundError`	404	Resource does not exist.
`ConflictError`	409	Resource already exists or state conflict.
`RateLimitError`	429	Too many requests from a single client.

The errorHandler middleware (backend/src/middlewares/errorHandler.js) is the final stop for every request.

Sentry Integration: If SENTRY_DSN is configured, all 500+ errors are automatically reported to Sentry.
Logging: All errors are logged locally via the loggerService.
Formatting: Errors are transformed into a standard JSON structure using errorFormatter.
Production Safety: In production, stack traces are stripped from 500 errors to avoid leaking internal details.

We use two utility objects in backend/src/utils/formatters/ to ensure the API always returns a predictable structure.

Used for all non-error responses.

{
  "status": "success",
  "message": "Operation successful",
  "data": { ... },
  "code": 200
}

formatSuccess(data, message, code): For single objects or simple operations.
formatList(items, total, page, limit): specifically for paginated lists, adding a pagination metadata object.

{
  "status": "error",
  "message": "Resource not found",
  "code": "NOT_FOUND",
  "statusCode": 404
}

Never res.send() directly: Always use the formatters in controllers.
Throw, don’t return: In services and repositories, throw the appropriate BaseError. The catchAsync wrapper in controllers will automatically pass it to the global error handler.
Operational vs. Programmer Errors: BaseError subclasses are considered “operational” (expected). Everything else is a “programmer error” and will result in a 500 status code.