Handling errors

Errors are a natural part of any backend application — whether they come from validation issues, authentication problems, permission checks, or unexpected runtime failures. Dotpress provides a clean and unified way to return HTTP errors directly from your route handlers.

Common errors

Use the built-in helpers to return common HTTP errors.

return badRequestError('Invalid email'); // 400
return unauthorizedError(); // 401
return forbiddenError('You do not have access'); // 403
return notFoundError('User not found'); // 404
return internalError('Something went wrong'); // 500

Each of these returns a structured JSON response:

{
  "status": 400,
  "error": "BAD_REQUEST",
  "message": "Your custom, optional message here or a default one."
}

Custom errors

If you need more control (e.g., custom status codes or additional metadata), use errorResponse:

return errorResponse(422, 'INVALID_STATE', 'Invalid state transition', {
  state: 'archived',
  previousState: 'pending',
});

Produces:

{
  "status": 422,
  "error": "INVALID_STATE",
  "message": "Invalid state transition",
  "data": {
    "state": "archived",
    "previousState": "pending"
  }
}

Notes

• You can return errors just like any other value — Dotpress detects and handles them automatically.
• No need to throw — you just have to return them to interrupt middleware or handler and generate a response.
• All unhandled exceptions are caught and returned as 500 Internal Server Error.