Error Handling Pattern | Bootspring Docs

Build consistent, type-safe API error responses with custom error classes, error handlers, and client-side error parsing.

Overview#

Consistent error handling is crucial for API usability and debugging. This pattern provides a structured approach to creating, throwing, and handling errors across your API routes.

When to use:

Building REST APIs that need consistent error formats
Implementing error boundaries for API routes
Creating reusable error handling utilities
Integrating with error tracking services

Key features:

Custom error classes with status codes
Consistent JSON error response format
Zod validation error handling
Error logging and tracking
Client-side error parsing

Code Example#

Error Classes#

// lib/errors.ts
export class AppError extends Error {
  constructor(
    message: string,
    public statusCode: number = 500,
    public code: string = 'INTERNAL_ERROR'
  ) {
    super(message)
    this.name = 'AppError'
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string) {
    super(`${resource} not found`, 404, 'NOT_FOUND')
    this.name = 'NotFoundError'
  }
}

export class UnauthorizedError extends AppError {
  constructor(message = 'Unauthorized') {
    super(message, 401, 'UNAUTHORIZED')
    this.name = 'UnauthorizedError'
  }
}

export class ForbiddenError extends AppError {
  constructor(message = 'Forbidden') {
    super(message, 403, 'FORBIDDEN')
    this.name = 'ForbiddenError'
  }
}

export class ValidationError extends AppError {
  constructor(
    message: string,
    public errors: Record<string, string[]> = {}
  ) {
    super(message, 400, 'VALIDATION_ERROR')
    this.name = 'ValidationError'
  }
}

export class ConflictError extends AppError {
  constructor(message: string) {
    super(message, 409, 'CONFLICT')
    this.name = 'ConflictError'
  }
}

export class RateLimitError extends AppError {
  constructor(retryAfter: number) {
    super('Too many requests', 429, 'RATE_LIMIT_EXCEEDED')
    this.name = 'RateLimitError'
  }
}

Error Response Format#

// lib/api-response.ts
interface ErrorResponse {
  error: {
    message: string
    code: string
    details?: Record<string, unknown>
  }
}

interface SuccessResponse<T> {
  data: T
}

export function errorResponse(
  error: AppError | Error
): { body: ErrorResponse; status: number } {
  if (error instanceof AppError) {
    return {
      body: {
        error: {
          message: error.message,
          code: error.code,
          details: error instanceof ValidationError ? { errors: error.errors } : undefined
        }
      },
      status: error.statusCode
    }
  }

  // Unknown error - don't expose details
  console.error('Unhandled error:', error)
  return {
    body: {
      error: {
        message: 'An unexpected error occurred',
        code: 'INTERNAL_ERROR'
      }
    },
    status: 500
  }
}

export function successResponse<T>(data: T): SuccessResponse<T> {
  return { data }
}

Error Handler Wrapper#

// lib/api-handler.ts
import { NextRequest, NextResponse } from 'next/server'
import { AppError, ValidationError, errorResponse } from '@/lib/errors'
import { ZodError } from 'zod'

type Handler = (request: NextRequest) => Promise<Response>

export function withErrorHandler(handler: Handler): Handler {
  return async (request: NextRequest) => {
    try {
      return await handler(request)
    } catch (error) {
      // Handle Zod validation errors
      if (error instanceof ZodError) {
        const validationError = new ValidationError(
          'Validation failed',
          formatZodErrors(error)
        )
        const { body, status } = errorResponse(validationError)
        return NextResponse.json(body, { status })
      }

      // Handle app errors
      if (error instanceof AppError) {
        const { body, status } = errorResponse(error)
        return NextResponse.json(body, { status })
      }

      // Handle unknown errors
      console.error('Unhandled API error:', error)
      return NextResponse.json(
        { error: { message: 'Internal server error', code: 'INTERNAL_ERROR' } },
        { status: 500 }
      )
    }
  }
}

function formatZodErrors(error: ZodError): Record<string, string[]> {
  const errors: Record<string, string[]> = {}

  for (const issue of error.issues) {
    const path = issue.path.join('.')
    if (!errors[path]) {
      errors[path] = []
    }
    errors[path].push(issue.message)
  }

  return errors
}

Route Handler with Error Handling#

// app/api/users/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { withErrorHandler } from '@/lib/api-handler'
import { NotFoundError, ForbiddenError, UnauthorizedError } from '@/lib/errors'
import { auth } from '@/auth'

export const GET = withErrorHandler(async (
  request: NextRequest,
  { params }: { params: { id: string } }
) => {
  const session = await auth()

  if (!session) {
    throw new UnauthorizedError()
  }

  const user = await prisma.user.findUnique({
    where: { id: params.id }
  })

  if (!user) {
    throw new NotFoundError('User')
  }

  if (user.id !== session.user.id && session.user.role !== 'ADMIN') {
    throw new ForbiddenError('Cannot access other users')
  }

  return NextResponse.json({ data: user })
})

Error Logging#

// lib/error-logger.ts
import { AppError } from './errors'

interface ErrorContext {
  userId?: string
  requestId?: string
  path?: string
  method?: string
}

export function logError(error: Error, context: ErrorContext = {}) {
  const isOperational = error instanceof AppError

  const logData = {
    message: error.message,
    stack: error.stack,
    isOperational,
    ...context,
    timestamp: new Date().toISOString()
  }

  if (isOperational) {
    console.warn('Operational error:', logData)
  } else {
    console.error('System error:', logData)
    // Send to error tracking service
    // await sendToSentry(error, context)
  }
}

Client-Side Error Handling#

// lib/api-client.ts
import { AppError } from './errors'

interface ApiError {
  error: {
    message: string
    code: string
    details?: Record<string, unknown>
  }
}

export async function apiRequest<T>(
  url: string,
  options?: RequestInit
): Promise<T> {
  const response = await fetch(url, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      ...options?.headers
    }
  })

  const data = await response.json()

  if (!response.ok) {
    const apiError = data as ApiError
    throw new AppError(
      apiError.error.message,
      response.status,
      apiError.error.code
    )
  }

  return data.data as T
}

// Usage
try {
  const user = await apiRequest<User>('/api/users/123')
} catch (error) {
  if (error instanceof AppError && error.code === 'NOT_FOUND') {
    // Handle not found
  }
}

Usage Instructions#

Create error classes: Define custom errors extending AppError
Wrap route handlers: Use withErrorHandler to catch and format errors
Throw specific errors: Use appropriate error classes in your handlers
Handle on client: Parse error responses using the API client
Log appropriately: Distinguish between operational and system errors

Best Practices#

Use specific error classes - Create errors for each failure type
Include error codes - Machine-readable codes for client handling
Hide internal details - Never expose stack traces or sensitive info in responses
Log system errors - Track unexpected errors for debugging
Distinguish error types - Operational errors (expected) vs system errors (bugs)
Validate early - Catch validation errors at the boundary
Use consistent format - Same structure for all error responses

Route Handler - API endpoint implementation
Middleware - Request preprocessing
Validation - Input validation with Zod
Logging - Structured logging setup