Api Reference

Name: ds-express-errors
Author: Diana Stoyka

Error Presets

All presets are available via the Errors object.

Method	Status Code	Description
`Errors.BadRequest(message)`	400	Bad Request
`Errors.Unauthorized(message)`	401	Unauthorized
`Errors.PaymentRequired(message)`	402	Payment Required
`Errors.Forbidden(message)`	403	Forbidden
`Errors.NotFound(message)`	404	Not Found
`Errors.Conflict(message)`	409	Conflict
`Errors.UnprocessableContent(message)`	422	Unprocessable Content
`Errors.TooManyRequests(message)`	429	TooManyRequests
`Errors.InternalServerError(message)`	500	Internal Server Error
`Errors.NotImplemented(message)`	501	Not Implemented
`Errors.BadGateway(message)`	502	Bad Gateway
`Errors.ServiceUnavailable(message)`	503	Service Unavailable

AppError Class

The base class for all errors. Use this if you need a custom status code.

typescript

new AppError(message: string, statusCode: number, isOperational: boolean = true)

Configuration

Environment variables that affect library behavior:

NODE_ENV:

development: Response includes stack trace.
production: stack trace, url, method are hidden.

DEBUG: Set to true to enable debug logs (e.g., viewing raw error details before mapping).

Configuration Options

Passed to setConfig(options):

Option	Type	Description	Default
`formatError`	`function`	Customize the JSON response structure.	`formatError: (err, {req, isDev}) => ({ status: err.isOperational ? 'fail' : 'error', message: err.message, ...(isDev ? { method: req.method, url: req.originalUrl, stack: err.stack } : {}) })`
`devEnvironments`	`string[]`	List of environments where stack traces, url, method are visible.	`devEnvironments: ['development', 'dev']`
`customMappers`	`function[]`	Array of functions to handle specific errors before the default logic.	`[]`
`customLogger`	`Object`	External logger (pino/winston) for custom logging	`null`

Example Client Response

Development mode:

JSON

{
  "status": "error",
  "method": "GET",
  "url": "/api/users/999",
  "message": "User not found",
  "stack": "Error: User not found
    at /app/controllers/user.js:15:20..."
}

Production mode:

JSON

{
  "status": "error",
  "message": "User not found"
}

Auto-Mapped Errors:

* Thrown by body-parser when JSON payload is malformed

Throw Error	Error Name
`400 BadRequest`	`BadRequest`
	`UnknownFieldsError`
	`ValidationError`
	`ZodError`
	`Joi Error`
	`CastError`
	`DuplicateKeyError`
	`SequelizeForeignKeyConstraintError`
	`SequelizeUniqueConstraintError`
	`SequelizeValidationError`
	`PrismaClientKnownRequestError`
	`PrismaClientUnknownRequestError`
	`SyntaxError (body-parser)*`
`401 Unauthorized`	`JsonWebTokenError`
	`TokenExpiredError`
	`NotBeforeError`
	`UnauthorizedError`
	`Unauthorized`
`402 PaymentRequired`	`PaymentRequired`
`403 Forbidden`	`Forbidden`
`403 Forbidden`	`ForbiddenError`
`404 NotFound`	`NotFound`
`404 NotFound`	`NotFoundError`
`409 Conflict`	`Conflict`
`409 Conflict`	`ConflictError`
`422 Unprocessable Content`	`FieldValidationError`
	`GroupedAlternativeValidationError`
	`AlternativeValidationError`
`429 TooManyRequests`	`TooManyRequests`
	`TooManyRequestsError`
	`RateLimitError`
`500 InternalServerError`	`InternalServerError`
`500 InternalServerError`	`SyntaxError`
`501 NotImplemented`	`NotImplemented`
`502 BadGateway`	`BadGateway`
`503 ServiceUnavailable`	`ServiceUnavailable`