ServiceUnavailableException

Kind: Class

Source: packages/common/exceptions/service-unavailable.exception.ts

Part of: 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.