# HttpException

**Kind:** Class

**Source:** [`packages/common/exceptions/http.exception.ts`](https://github.com/nestjs/nest/blob/master/packages/common/exceptions/http.exception.ts#L27)

**Part of:** [Common](subsystem-packages-common)

Defines the base Nest HTTP exception, which is handled by the default
Exceptions Handler.

`HttpException` is Nest’s base error type for representing HTTP failures with a response payload and status code. When thrown from application code, it is processed by Nest’s default exceptions handler to produce a structured HTTP error response.

**Extends:** `IntrinsicException`

## Methods

| Method | Signature | Returns |
|---|---|---|
| `initCause` | `initCause()` | `void` |
| `initMessage` | `initMessage()` | `void` |
| `initName` | `initName()` | `void` |
| `getResponse` | `getResponse()` | `string | object` |
| `getStatus` | `getStatus()` | `number` |
| `createBody` | `createBody(nil: null | '', message: HttpExceptionBodyMessage, statusCode: number)` | `HttpExceptionBody` |
| `createBody` | `createBody(message: HttpExceptionBodyMessage, error: string, statusCode: number)` | `HttpExceptionBody` |
| `createBody` | `createBody(custom: Body)` | `Body` |
| `createBody` | `createBody(arg0: null | HttpExceptionBodyMessage | Body, arg1: HttpExceptionBodyMessage | string, statusCode: number)` | `HttpExceptionBody | Body` |
| `getDescriptionFrom` | `getDescriptionFrom(descriptionOrOptions: string | HttpExceptionOptions)` | `string` |
| `getHttpExceptionOptionsFrom` | `getHttpExceptionOptionsFrom(descriptionOrOptions: string | HttpExceptionOptions)` | `HttpExceptionOptions` |
| `extractDescriptionAndOptionsFrom` | `extractDescriptionAndOptionsFrom(descriptionOrOptions: string | HttpExceptionOptions)` | `DescriptionAndOptions` |

## Properties

| Property | Type |
|---|---|
| `cause` | `unknown` |

## Where it refuses work

- `HttpException` stops the work with an early return when `!arg0`.
- `HttpException` stops the work with an early return when `isString(arg0) || Array.isArray(arg0) || isNumber(arg0)`.

## Diagram

```mermaid
graph LR
  A[Controller / Service] -->|throw new HttpException| B[HttpException]
  B --> C[getStatus()]
  B --> D[getResponse()]
  B --> E[Default Exceptions Handler]
  C --> E
  D --> E
  E --> F[HTTP Error Response]
```

## Usage

```ts
import { Controller, Get, HttpException, HttpStatus } from '@nestjs/common';

@Controller('reports')
export class ReportsController {
  @Get()
  getReport() {
    const reportAvailable = false;

    if (!reportAvailable) {
      throw new HttpException(
        {
          statusCode: HttpStatus.NOT_FOUND,
          message: 'Report not found',
          error: 'Not Found',
        },
        HttpStatus.NOT_FOUND,
      );
    }

    return { id: 'report-123' };
  }
}
```

## AI Coding Instructions

- Throw `HttpException` when a request should end with a specific HTTP status and response body.
- Use Nest’s `HttpStatus` enum instead of hard-coded numeric status codes.
- Pass either a string or a structured object as the response; `getResponse()` returns the original payload.
- Prefer specialized exceptions such as `NotFoundException` or `BadRequestException` when they match the intended status.
- Use `HttpException.createBody()` when building standardized error response payloads for custom exceptions.

## Used by

10 references from 10 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.

### Imported by (10)

- `RoutesResolver` — `packages/core/router/routes-resolver.ts`:35
- `ErrorsInterceptor` — `sample/01-cats-app/src/common/interceptors/exception.interceptor.ts`:12
- `ExceptionInterceptor` — `sample/10-fastify/src/common/interceptors/exception.interceptor.ts`:12
- `ErrorsInterceptor` — `sample/36-hmr-esm/src/common/interceptors/exception.interceptor.ts`:12
- `HttpExceptionFilter` — `integration/inspector/src/common/filters/http-exception.filter.ts`:8
- `BaseExceptionFilter` — `packages/core/exceptions/base-exception-filter.ts`:17
- `ExceptionsHandler` — `packages/core/exceptions/exceptions-handler.ts`:9
- `transformException` — `packages/platform-express/multer/multer/multer.utils.ts`:10

…and 2 more.