feat(common): add payment required exception for http 402

402 is the only status code in the 400-422 range without a dedicated
HttpException subclass. The HttpStatus.PAYMENT_REQUIRED enum entry
already exists, but throwing it requires the verbose form
'new HttpException(msg, HttpStatus.PAYMENT_REQUIRED)'.

Add PaymentRequiredException mirroring ImATeapotException for symmetry
with the other 21 sibling exceptions, export it from the barrel, and
extend the parametric tests in http.exception.spec.ts.

Author: LOsioChico

packages/common/exceptions/index.ts

@@ -15,6 +15,7 @@ export * from './not-acceptable.exception';
 export * from './not-found.exception';
 export * from './not-implemented.exception';
 export * from './payload-too-large.exception';
+export * from './payment-required.exception';
 export * from './precondition-failed.exception';
 export * from './request-timeout.exception';
 export * from './service-unavailable.exception';

packages/common/exceptions/payment-required.exception.ts

@@ -0,0 +1,53 @@
+import { HttpStatus } from '../enums/http-status.enum';
+import { HttpException, HttpExceptionOptions } from './http.exception';
+
+/**
+ * Defines an HTTP exception for *Payment Required* type errors.
+ *
+ * @see [Built-in HTTP exceptions](https://docs.nestjs.com/exception-filters#built-in-http-exceptions)
+ *
+ * @publicApi
+ */
+export class PaymentRequiredException extends HttpException {
+  /**
+   * Instantiate a `PaymentRequiredException` Exception.
+   *
+   * @example
+   * `throw new PaymentRequiredException()`
+   *
+   * @usageNotes
+   * The HTTP response status code will be 402.
+   * - The `objectOrError` argument defines the JSON response body or the message string.
+   * - The `descriptionOrOptions` argument contains either a short description of the HTTP error or an options object used to provide an underlying error cause.
+   *
+   * By default, the JSON response body contains two properties:
+   * - `statusCode`: this will be the value 402.
+   * - `message`: the string `'Payment Required'` by default; override this by supplying
+   * a string in the `objectOrError` parameter.
+   *
+   * If the parameter `objectOrError` is a string, the response body will contain an
+   * additional property, `error`, with a short description of the HTTP error. To override the
+   * entire JSON response body, pass an object instead. Nest will serialize the object
+   * and return it as the JSON response body.
+   *
+   * @param objectOrError string or object describing the error condition.
+   * @param descriptionOrOptions either a short description of the HTTP error or an options object used to provide an underlying error cause
+   */
+  constructor(
+    objectOrError?: any,
+    descriptionOrOptions: string | HttpExceptionOptions = 'Payment Required',
+  ) {
+    const { description, httpExceptionOptions } =
+      HttpException.extractDescriptionAndOptionsFrom(descriptionOrOptions);
+
+    super(
+      HttpException.createBody(
+        objectOrError,
+        description!,
+        HttpStatus.PAYMENT_REQUIRED,
+      ),
+      HttpStatus.PAYMENT_REQUIRED,
+      httpExceptionOptions,
+    );
+  }
+}

packages/common/test/exceptions/http.exception.spec.ts

@@ -17,6 +17,7 @@ import {
   NotFoundException,
   NotImplementedException,
   PayloadTooLargeException,
+  PaymentRequiredException,
   PreconditionFailedException,
   RequestTimeoutException,
   ServiceUnavailableException,
@@ -66,6 +67,7 @@ describe('HttpException', () => {
         const testCases: [Type<HttpException>, number][] = [
           [BadRequestException, 400],
           [UnauthorizedException, 401],
+          [PaymentRequiredException, 402],
           [ForbiddenException, 403],
           [NotFoundException, 404],
           [MethodNotAllowedException, 405],
@@ -98,6 +100,7 @@ describe('HttpException', () => {
         const testCases: [Type<HttpException>, number, string][] = [
           [BadRequestException, 400, 'Bad Request'],
           [UnauthorizedException, 401, 'Unauthorized'],
+          [PaymentRequiredException, 402, 'Payment Required'],
           [ForbiddenException, 403, 'Forbidden'],
           [NotFoundException, 404, 'Not Found'],
           [MethodNotAllowedException, 405, 'Method Not Allowed'],
@@ -248,6 +251,7 @@ describe('HttpException', () => {
         NotFoundException,
         NotImplementedException,
         PayloadTooLargeException,
+        PaymentRequiredException,
         PreconditionFailedException,
         RequestTimeoutException,
         ServiceUnavailableException,