Error Handling Pattern | Bootspring Docs

Implement consistent, type-safe error handling across your application with custom error classes and handlers.

Overview#

Proper error handling improves debugging, user experience, and application reliability. This pattern provides a structured approach to creating, throwing, catching, and displaying errors consistently.

When to use:

API error responses
Client-side error handling
Error logging and monitoring
User-friendly error messages
Validation error display

Key features:

Custom error classes
Consistent error format
API error wrapper
Client error handling
Error logging
React error boundaries

Code Example#

Custom 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(
    public retryAfter: number,
    message = 'Too many requests'
  ) {
    super(message, 429, 'RATE_LIMIT_EXCEEDED')
    this.name = 'RateLimitError'
  }
}

Error Response Format#

// lib/api-response.ts
import { AppError, ValidationError } from './errors'

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 in production
  console.error('Unhandled error:', error)
  return {
    body: {
      error: {
        message: process.env.NODE_ENV === 'development'
          ? error.message
          : 'An unexpected error occurred',
        code: 'INTERNAL_ERROR'
      }
    },
    status: 500
  }
}

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

API 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, context?: any) => Promise<Response>

export function withErrorHandler(handler: Handler): Handler {
  return async (request: NextRequest, context?: any) => {
    try {
      return await handler(request, context)
    } 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 Usage#

// 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 '@/lib/auth'
import { prisma } from '@/lib/db'

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

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

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

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

  if (user.id !== userId) {
    throw new ForbiddenError('Cannot access other users')
  }

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

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
async function fetchUser(id: string) {
  try {
    const user = await apiRequest<User>(`/api/users/${id}`)
    return user
  } catch (error) {
    if (error instanceof AppError) {
      if (error.code === 'NOT_FOUND') {
        // Handle not found
      }
      if (error.code === 'UNAUTHORIZED') {
        // Redirect to login
      }
    }
    throw error
  }
}

Error Logging#

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

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

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

  const logData = {
    message: error.message,
    name: error.name,
    stack: error.stack,
    isOperational,
    code: error instanceof AppError ? error.code : undefined,
    ...context,
    timestamp: new Date().toISOString()
  }

  if (isOperational) {
    // Expected errors - warn level
    console.warn('Operational error:', JSON.stringify(logData))
  } else {
    // Unexpected errors - error level
    console.error('System error:', JSON.stringify(logData))

    // Send to error tracking service in production
    if (process.env.NODE_ENV === 'production') {
      // sendToSentry(error, context)
      // sendToDatadog(error, context)
    }
  }
}

React Error Boundary#

// components/ErrorBoundary.tsx
'use client'

import { Component, ReactNode } from 'react'

interface Props {
  children: ReactNode
  fallback?: ReactNode
}

interface State {
  hasError: boolean
  error?: Error
}

export class ErrorBoundary extends Component<Props, State> {
  constructor(props: Props) {
    super(props)
    this.state = { hasError: false }
  }

  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error }
  }

  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
    console.error('Error caught by boundary:', error, errorInfo)
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback ?? (
        <div className="p-4 text-center">
          <h2 className="text-lg font-semibold text-red-600">
            Something went wrong
          </h2>
          <p className="text-gray-600">
            {this.state.error?.message ?? 'An unexpected error occurred'}
          </p>
          <button
            onClick={() => this.setState({ hasError: false })}
            className="mt-4 px-4 py-2 bg-blue-500 text-white rounded"
          >
            Try again
          </button>
        </div>
      )
    }

    return this.props.children
  }
}

Error Display Component#

// components/ErrorMessage.tsx
interface ErrorMessageProps {
  error?: string | null
  className?: string
}

export function ErrorMessage({ error, className }: ErrorMessageProps) {
  if (!error) return null

  return (
    <p
      className={`text-sm text-red-600 ${className ?? ''}`}
      role="alert"
    >
      {error}
    </p>
  )
}

// Field error for forms
interface FieldErrorProps {
  name: string
  errors?: Record<string, string>
}

export function FieldError({ name, errors }: FieldErrorProps) {
  const error = errors?.[name]
  if (!error) return null

  return (
    <p
      className="mt-1 text-sm text-red-600"
      role="alert"
      id={`${name}-error`}
    >
      {error}
    </p>
  )
}

Toast Notifications for Errors#

// lib/toast.ts
import { toast } from 'sonner'
import { AppError } from './errors'

export function showErrorToast(error: unknown) {
  if (error instanceof AppError) {
    toast.error(error.message, {
      description: getErrorDescription(error.code)
    })
  } else if (error instanceof Error) {
    toast.error('An error occurred', {
      description: error.message
    })
  } else {
    toast.error('An unexpected error occurred')
  }
}

function getErrorDescription(code: string): string | undefined {
  const descriptions: Record<string, string> = {
    UNAUTHORIZED: 'Please sign in to continue',
    FORBIDDEN: 'You do not have permission for this action',
    NOT_FOUND: 'The requested resource was not found',
    RATE_LIMIT_EXCEEDED: 'Please wait before trying again',
    VALIDATION_ERROR: 'Please check your input and try again'
  }
  return descriptions[code]
}

Usage Instructions#

Create error classes: Define custom errors for each error type
Wrap API handlers: Use withErrorHandler for consistent responses
Throw specific errors: Use the right error class for each situation
Handle on client: Catch errors and display appropriate messages
Log appropriately: Track errors for debugging and monitoring

Best Practices#

Use specific error classes - Create errors for each scenario
Include error codes - Enable programmatic error handling
Don't leak internal details - Sanitize messages in production
Log with context - Include request ID, user ID, etc.
Handle gracefully - Always show user-friendly messages
Use error boundaries - Prevent component crashes from breaking the app
Monitor in production - Use Sentry, Datadog, or similar
Test error paths - Verify error handling works correctly

Validation - Input validation errors
API Error Handling - REST API errors
Forms - Form error display