# ForbiddenException

**Kind:** Class

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

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

Defines an HTTP exception for *Forbidden* type errors.

`ForbiddenException` represents an HTTP 403 error, indicating that a request was understood but the authenticated user does not have permission to perform the requested action. It extends the framework's HTTP exception handling system so controllers, guards, and services can signal authorization failures consistently. Use it when access is denied due to insufficient roles, ownership, or policy permissions.

**Extends:** `HttpException`

## Diagram

```mermaid
graph LR
  A[Incoming request] --> B[Authorization check]
  B -->|Permission granted| C[Continue request handling]
  B -->|Permission denied| D[ForbiddenException]
  D --> E[HTTP 403 Forbidden response]
```

## Usage

```ts
import { ForbiddenException } from '@nestjs/common';

function updateProject(userId: string, project: { ownerId: string }) {
  if (project.ownerId !== userId) {
    throw new ForbiddenException(
      'You do not have permission to update this project.',
    );
  }

  return { success: true };
}
```

## AI Coding Instructions

- Throw `ForbiddenException` only for authorization failures; use `UnauthorizedException` when the user is not authenticated.
- Perform role, ownership, or policy checks before executing protected mutations or exposing restricted data.
- Provide a clear, safe error message, but do not reveal sensitive permission rules or internal resource details.
- Prefer using guards or centralized authorization policies for reusable access-control logic rather than duplicating checks across controllers.

## Used by

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

### Imported by (2)

- `ParamProperties` — `packages/core/router/router-execution-context.ts`:50
- `ParamsFactory` — `packages/core/helpers/external-context-creator.ts`:28