Professional Error Handling

TaskFlow Phase 13 - Professional Error Handling

This snapshot contains the files changed by Phase 13. It assumes the Phase 12 project already exists.

Main additions:
- one consistent API error response shape
- a catch-all NestJS exception filter using HttpAdapterHost
- Prisma P2002/P2003/P2025 translation
- domain-specific not-found exceptions
- Fastify request IDs surfaced to clients and logs
- NestJS 12 structured logging metadata
- a small Next.js-side API error parser

Run apps/api, then execute tests/error-contract-smoke-tests.ps1.

import { Module } from "@nestjs/common";
import { APP_FILTER, APP_INTERCEPTOR } from "@nestjs/core";
import { ApiExceptionFilter } from "./common/errors/api-exception.filter";
import { RequestLoggingInterceptor } from "./common/interceptors/request-logging.interceptor";
import { HealthModule } from "./health/health.module";
import { PrismaModule } from "./prisma/prisma.module";
import { TasksModule } from "./tasks/tasks.module";

@Module({
  imports: [
    HealthModule,
    PrismaModule,
    TasksModule,
  ],
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: RequestLoggingInterceptor,
    },
    {

export type ApiErrorDetails = string[] | Record<string, unknown>;

export type ApiErrorResponse = {
  statusCode: number;
  code: string;
  message: string;
  requestId: string;
  timestamp: string;
  path: string;
  details?: ApiErrorDetails;
};

import {
  ArgumentsHost,
  Catch,
  ExceptionFilter,
  HttpException,
  HttpStatus,
  Logger,
} from "@nestjs/common";
import { HttpAdapterHost } from "@nestjs/core";
import { FastifyRequest } from "fastify";
import { Prisma } from "../../generated/prisma/client";
import { ApiErrorResponse } from "./api-error-response";

@Catch()
export class ApiExceptionFilter implements ExceptionFilter {
  private readonly logger = new Logger(ApiExceptionFilter.name);

  constructor(private readonly httpAdapterHost: HttpAdapterHost) {}

  catch(exception: unknown, host: ArgumentsHost): void {

import {
  ConflictException,
  NotFoundException,
} from "@nestjs/common";

export class TaskNotFoundException extends NotFoundException {
  constructor(taskId: string) {
    super({
      code: "TASK_NOT_FOUND",
      message: `Task ${taskId} was not found.`,
    });
  }
}

export class ProjectNotFoundException extends NotFoundException {
  constructor(projectId: string) {
    super({
      code: "PROJECT_NOT_FOUND",
      message: `Project ${projectId} was not found.`,
    });

import {
  CallHandler,
  ExecutionContext,
  Injectable,
  Logger,
  NestInterceptor,
} from "@nestjs/common";
import { FastifyReply, FastifyRequest } from "fastify";
import { Observable } from "rxjs";
import { tap } from "rxjs/operators";

@Injectable()
export class RequestLoggingInterceptor implements NestInterceptor {
  private readonly logger = new Logger(RequestLoggingInterceptor.name);

  intercept(
    context: ExecutionContext,
    next: CallHandler,
  ): Observable<unknown> {
    const http = context.switchToHttp();

import { Injectable } from "@nestjs/common";
import { Prisma } from "../generated/prisma/client";
import { PrismaService } from "../prisma/prisma.service";
import {
  ProjectNotFoundException,
  TaskNotFoundException,
} from "../common/errors/application.exceptions";
import {
  CreateTaskDto,
  UpdateTaskDto,
} from "./tasks.schemas";

@Injectable()
export class TasksService {
  constructor(private readonly prisma: PrismaService) {}

  findAll() {
    return this.prisma.task.findMany({
      orderBy: { createdAt: "desc" },
    });

export type ApiErrorResponse = {
  statusCode: number;
  code: string;
  message: string;
  requestId: string;
  timestamp: string;
  path: string;
  details?: string[] | Record<string, unknown>;
};

export class ApiClientError extends Error {
  constructor(
    public readonly statusCode: number,
    public readonly code: string,
    message: string,
    public readonly requestId?: string,
    public readonly details?: ApiErrorResponse["details"],
  ) {
    super(message);
  }

# TaskFlow Phase 13 error-contract smoke tests
# Run while apps/api is running on http://localhost:4000

$base = "http://localhost:4000"

function Show-ErrorContract {
  param([scriptblock]$Request)

  try {
    & $Request
  }
  catch {
    $response = $_.Exception.Response

    if ($null -eq $response) {
      Write-Host "No HTTP response was returned."
      throw
    }

    $body = $_.ErrorDetails.Message | ConvertFrom-Json