# ServiceUnavailableException

**Kind:** Class

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

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

Defines an HTTP exception for *Service Unavailable* type errors.

`ServiceUnavailableException` represents an HTTP 503 Service Unavailable error. Use it when a request cannot be fulfilled because a dependency, downstream service, or the application itself is temporarily unavailable. It integrates with the framework's exception handling pipeline to produce a consistent HTTP error response.

**Extends:** `HttpException`

## Diagram

```mermaid
graph LR
  A[Request Handler] --> B{Required service available?}
  B -->|Yes| C[Return successful response]
  B -->|No| D[Throw ServiceUnavailableException]
  D --> E[Exception Filter]
  E --> F[HTTP 503 Service Unavailable Response]
```

## Usage

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

async function fetchInventory(productId: string) {
  const inventoryService = await getInventoryService();

  if (!inventoryService.isAvailable()) {
    throw new ServiceUnavailableException(
      'Inventory service is temporarily unavailable',
    );
  }

  return inventoryService.getStock(productId);
}
```

## AI Coding Instructions

- Throw `ServiceUnavailableException` only for temporary availability failures that should return HTTP status `503`.
- Include a clear, client-safe message describing the unavailable dependency or service state.
- Prefer this exception over generic internal-server errors when retries may succeed after the service recovers.
- Ensure upstream health checks, circuit breakers, or dependency clients surface availability failures consistently.