Merge pull request #2522 from thiagomini/patch-5

docs(exception-filters): docs for error options

Author: kamilmysliwiec

content/exception-filters.md

@@ -60,16 +60,24 @@ in the `response` argument. To override the entire JSON response body, pass an o
 The second constructor argument - `status` - should be a valid HTTP status code.
 Best practice is to use the `HttpStatus` enum imported from `@nestjs/common`.
 
-Here's an example overriding the entire response body:
+There is a **third** constructor argument (optional) - `options` - that can be used to provide an error [cause](https://nodejs.org/en/blog/release/v16.9.0/#error-cause). This `cause` object is not serialized into the response object, but it can be useful for logging purposes, providing valuable information about the inner error that caused the `HttpException` to be thrown.
+
+Here's an example overriding the entire response body and providing an error cause:
 
 ```typescript
 @@filename(cats.controller)
 @Get()
 async findAll() {
-  throw new HttpException({
+  try {
+    await this.service.findAll()
+  } catch (error) { 
+    throw new HttpException({
     status: HttpStatus.FORBIDDEN,
     error: 'This is a custom message',
-  }, HttpStatus.FORBIDDEN);
+  }, HttpStatus.FORBIDDEN, {
+    cause: error
+  });
+  }
 }
 ```
 
@@ -130,6 +138,22 @@ Nest provides a set of standard exceptions that inherit from the base `HttpExcep
 - `GatewayTimeoutException`
 - `PreconditionFailedException`
 
+All the built-in exceptions can also provide both an error `cause` and an error description using the `options` parameter:
+
+```typescript
+throw new BadRequestException('Something bad happened', { cause: new Error(), description: 'Some error description' })
+```
+
+Using the above, this is how the response would look:
+
+```json
+{
+  "message": "Something bad happened",
+  "error": "Some error description",
+  "statusCode": 400,
+}
+```
+
 #### Exception filters
 
 While the base (built-in) exception filter can automatically handle many cases for you, you may want **full control** over the exceptions layer. For example, you may want to add logging or use a different JSON schema based on some dynamic factors. **Exception filters** are designed for exactly this purpose. They let you control the exact flow of control and the content of the response sent back to the client.