Skip to main content

Error Components

The Error Components provide comprehensive error handling and user feedback for various error scenarios in the WorkPayCore Frontend application. These components handle everything from network errors to permission issues and application crashes.

Overview​

This document covers all error-related components that provide user-friendly error displays, fallback UI for error boundaries, and specialized error handling for different scenarios.

Components Overview​

Core Error Components​

HTTP Error Components​

Specialized Error Components​

  • PayoutActivation - Payout activation error handler
  • Error500 - 500 server error component

ErrorBoundary​

A React error boundary component that integrates with Sentry for error tracking and provides fallback UI when JavaScript errors occur.

Component Location​

import { ErrorBoundary } from 'components/Errors/ErroBoundary';

Props​

PropTypeRequiredDefaultDescription
childrenReactNode✓-Components to wrap with error boundary
fallbackReactNode-ErroBoundaryFallbackCustom fallback component

TypeScript Interface​

interface ErrorBoundaryProps {
  children: React.ReactNode;
  fallback?: React.ReactNode;
}

Features​

Sentry Integration​

  • Automatic error reporting to Sentry
  • Error tracking with user context
  • Performance monitoring integration
  • Error breadcrumbs and stack traces

Custom Fallback Support​

  • Default fallback UI with recovery options
  • Support for custom fallback components
  • Graceful degradation for component crashes

Usage Examples​

Basic Usage​

import { ErrorBoundary } from 'components/Errors/ErroBoundary';

function App() {
  return (
    <ErrorBoundary>
      <Dashboard />
      <Routes />
    </ErrorBoundary>
  );
}

With Custom Fallback​

import { ErrorBoundary } from 'components/Errors/ErroBoundary';

function CustomErrorFallback() {
  return (
    <Box p={8} textAlign='center'>
      &lt;Heading&gt;Something went wrong</Heading>
      &lt;Text&gt;Please try refreshing the page</Text>
      <Button onClick={() => window.location.reload()}>Refresh</Button>
    </Box>
  );
}

function AppWithCustomError() {
  return (
    <ErrorBoundary fallback={<CustomErrorFallback />}>
      <CriticalComponent />
    </ErrorBoundary>
  );
}

Component-Level Protection​

import { ErrorBoundary } from 'components/Errors/ErroBoundary';

function PayrollModule() {
  return (
    &lt;ErrorBoundary&gt;
      <PayrollDashboard />
      <PayrollTables />
      <PayrollActions />
    </ErrorBoundary>
  );
}

ErroBoundaryFallback​

The default fallback component for error boundaries, providing user-friendly error display with recovery options.

Component Location​

import { ErroBoundaryFallback } from 'components/Errors/ErroBoundaryFallback';

Props​

No props required - this is a self-contained fallback component.

Features​

Error Recovery Options​

  • Automatic page refresh detection
  • "Go to home" navigation option
  • "Refresh page" action button
  • Conditional button display based on current route

User-Friendly Design​

  • Broken page illustration
  • Clear error messaging
  • Actionable recovery options
  • Responsive layout

Smart Behavior​

  • Detects route changes and auto-refreshes
  • Hides "Go to home" button when already on home page
  • Path-aware recovery suggestions

Usage Examples​

As Default Fallback​

import { ErrorBoundary } from 'components/Errors/ErroBoundary';

function App() {
  return (
    &lt;ErrorBoundary&gt;
      {/* Uses ErroBoundaryFallback by default */}
      <ApplicationContent />
    </ErrorBoundary>
  );
}

Direct Usage​

import { ErroBoundaryFallback } from 'components/Errors/ErroBoundaryFallback';

function CustomErrorBoundary() {
  return (
    <div>
      <ErroBoundaryFallback />
    </div>
  );
}

Styling​

  • Height: 80vh (centered vertically)
  • Illustration: Broken page SVG (165px × 195px)
  • Typography: Clear hierarchical text styling
  • Colors: WorkPay brand colors (#62A446, #387E1B)
  • Buttons: Solid and outline variants

Fallback​

A generic error fallback component for 500-level server errors with branded styling.

Component Location​

import Fallback from 'components/Errors/Fallback';

Props​

No props required - this is a stateless error display component.

Features​

Server Error Display​

  • 500 error illustration
  • Professional error messaging
  • Branded WorkPay styling
  • Full viewport coverage

User Communication​

  • Clear error acknowledgment
  • Engineering team notification
  • Professional tone and messaging

Usage Examples​

Basic Usage​

import Fallback from 'components/Errors/Fallback';

function ServerErrorPage() {
  return <Fallback />;
}

Conditional Rendering​

import Fallback from 'components/Errors/Fallback';

function DataComponent() {
  const { data, error, isLoading } = useQuery('data');

  if (error?.status >= 500) {
    return <Fallback />;
  }

  return <DataDisplay data={data} />;
}

Styling​

  • Height: 100vh (full viewport)
  • Layout: Centered flexbox
  • Typography: Aller font family
  • Colors: WorkPay brand colors
  • Illustration: 500 error SVG (400px × 400px)

NotFound​

A 404 page not found component with navigation options back to the application.

Component Location​

import NotFound from 'components/Errors/NotFound';

Props​

PropTypeRequiredDefaultDescription
tostring-'/'Navigation destination
btnTextstring-'Go to Dashboard'Button text for navigation

TypeScript Interface​

interface NotFoundProps {
  to?: string;
  btnText?: string;
}

Features​

404 Error Display​

  • Clear "Page Not Found" messaging
  • 404 illustration with branding
  • User-friendly explanatory text
  • Customizable navigation destination
  • Customizable button text
  • React Router integration

Usage Examples​

Basic Usage​

import NotFound from 'components/Errors/NotFound';

function PageNotFound() {
  return <NotFound />;
}

Custom Navigation​

import NotFound from 'components/Errors/NotFound';

function CustomNotFound() {
  return <NotFound to='/employees' btnText='Go to Employees' />;
}

Route Integration​

import NotFound from 'components/Errors/NotFound';

function Routes() {
  return (
    &lt;Routes&gt;
      <Route path='/dashboard' element={<Dashboard />} />
      <Route path='/employees' element={<Employees />} />
      <Route path='*' element={<NotFound />} />
    </Routes>
  );
}

Styling​

  • Typography: 3xl heading with normal weight
  • Colors: Charcoal text color
  • Layout: Centered with spacing
  • Illustration: 404 SVG (350px height)
  • Button: Outline variant with 200px width

PermissionDenied​

A 403 permission denied component for unauthorized access scenarios.

Component Location​

import PermissionDenied from 'components/Errors/PermissionDenied';

Props​

No props required - this is a stateless permission error component.

Features​

Permission Error Display​

  • Clear "Permission Denied" messaging
  • 403 illustration with security theme
  • Admin contact instructions

User Guidance​

  • Clear explanation of access restriction
  • Actionable next steps
  • Professional error communication

Usage Examples​

Basic Usage​

import PermissionDenied from 'components/Errors/PermissionDenied';

function UnauthorizedPage() {
  return <PermissionDenied />;
}

Conditional Rendering​

import PermissionDenied from 'components/Errors/PermissionDenied';

function ProtectedComponent() {
  const { user } = useAuth();

  if (!user.hasPermission('view_admin_panel')) {
    return <PermissionDenied />;
  }

  return <AdminPanel />;
}

Route Protection​

import PermissionDenied from 'components/Errors/PermissionDenied';

function ProtectedRoute({ children, permission }) {
  const { user } = useAuth();

  if (!user.hasPermission(permission)) {
    return <PermissionDenied />;
  }

  return children;
}

Styling​

  • Typography: 3xl heading with normal weight
  • Colors: Charcoal text color
  • Layout: Centered full-width layout
  • Illustration: 403 permission denied SVG (300px height)

TableError​

A specialized error component for handling various HTTP errors in table contexts with appropriate fallback displays.

Component Location​

import TableError from 'components/Errors/TableError';

Props​

PropTypeRequiredDescription
errorErrorObject✓Error object with status and data

TypeScript Interface​

interface ErrorObject {
  status: number;
  data?: {
    message?: string | string[] | object;
    success?: boolean;
  };
  config?: {
    baseURL?: string;
  };
}

interface TableErrorProps {
  error: ErrorObject;
}

Features​

Multi-Status Error Handling​

  • 400 Bad Request: Resource doesn't exist
  • 403 Forbidden: Permission denied with logout handling
  • 404 Not Found: Resource not found
  • 422 Validation Error: Validation errors with detailed messages
  • 500+ Server Error: Generic server error fallback

Smart Error Processing​

  • Automatic logout for authentication errors
  • Validation error list formatting
  • Contextual error messaging
  • Appropriate illustrations for each error type

Usage Examples​

Basic Usage​

import TableError from 'components/Errors/TableError';

function DataTable() {
  const { data, error, isLoading } = useQuery('tableData');

  if (error) {
    return <TableError error={error} />;
  }

  return <Table data={data} />;
}

Custom Error Handling​

import TableError, { Error500 } from 'components/Errors/TableError';

function AdvancedTable() {
  const { data, error } = useQuery('data');

  if (error) {
    // Handle specific error types
    if (error.status === 500) {
      return <Error500 />;
    }

    return <TableError error={error} />;
  }

  return <DataTable data={data} />;
}

Error Boundary Integration​

import TableError from 'components/Errors/TableError';

function TableWithErrorBoundary() {
  return (
    <ErrorBoundary fallback={<TableError error={{ status: 500 }} />}>
      <ComplexTable />
    </ErrorBoundary>
  );
}

Error Status Handling​

400 Bad Request​

  • Shows resource doesn't exist message
  • Uses 403 illustration
  • Displays API error message if available

403 Forbidden​

  • Shows permission denied message
  • Handles automatic logout for authentication errors
  • Displays contact admin instructions

404 Not Found​

  • Shows resource not found message
  • Uses 404 illustration
  • Displays custom error message

422 Validation Error​

  • Shows validation error details
  • Supports both string and object error messages
  • Lists multiple validation errors

500+ Server Error​

  • Shows generic server error
  • Uses Error500 component
  • Provides engineering team message

PayoutActivation​

A specialized error component for payout activation and accessibility issues with detailed activation instructions.

Component Location​

import PayoutActivation from 'components/Errors/PayoutActivation';

Props​

PropTypeRequiredDescription
errorstring✓Error message string

TypeScript Interface​

interface PayoutActivationProps {
  error: string;
}

Features​

Payout Error Types​

  • Activation Error: Payouts not activated for company
  • Accessibility Error: Payouts not accessible at current time
  • Fallback Error: Generic server error display

Activation Guidance​

  • Document requirement checklist
  • Email template for support contact
  • Company-specific messaging
  • Professional styling and branding

Required Documents List​

  1. Company Registration Certificate
  2. Company Pin Certificate
  3. Company CR12
  4. Company Directors
  5. ID Copy
  6. Pin Certificate
  7. Additional user documentation

Usage Examples​

Basic Usage​

import PayoutActivation from 'components/Errors/PayoutActivation';

function PayoutErrorHandler({ error }) {
  return <PayoutActivation error={error.message} />;
}

Conditional Error Display​

import PayoutActivation from 'components/Errors/PayoutActivation';

function PayoutComponent() {
  const { error } = usePayoutStatus();

  if (error?.includes('activation')) {
    return <PayoutActivation error={error} />;
  }

  return <PayoutDashboard />;
}

Styling​

  • Layout: Responsive flex layout
  • Typography: Highlighted company names
  • Colors: WorkPay brand colors with gradients
  • Illustrations: Payout-specific SVG graphics
  • Documents: Numbered badge list styling

Error Handling Patterns​

Error Boundary Strategy​

// Application-level error boundary
function App() {
  return (
    &lt;ErrorBoundary&gt;
      &lt;Router&gt;
        &lt;Routes&gt;
          <Route path='/' element={<Dashboard />} />
          <Route
            path='/employees'
            element={
              &lt;ErrorBoundary&gt;
                <EmployeeModule />
              </ErrorBoundary>
            }
          />
          <Route path='*' element={<NotFound />} />
        </Routes>
      </Router>
    </ErrorBoundary>
  );
}

HTTP Error Handling​

// Custom hook for error handling
function useErrorHandler() {
  const handleError = error => {
    switch (error.status) {
      case 400:
        return <TableError error={error} />;
      case 403:
        return <PermissionDenied />;
      case 404:
        return <NotFound />;
      case 422:
        return <TableError error={error} />;
      default:
        return <Fallback />;
    }
  };

  return { handleError };
}

Specialized Error Routing​

// Error-specific routing
function ErrorRouter({ error }) {
  if (error.message.includes('payout')) {
    return <PayoutActivation error={error.message} />;
  }

  if (error.status === 403) {
    return <PermissionDenied />;
  }

  return <TableError error={error} />;
}

Error Recovery Patterns​

// Error recovery with retry logic
function DataComponentWithRetry() {
  const [retryCount, setRetryCount] = useState(0);
  const { data, error, refetch } = useQuery('data', {
    retry: retryCount < 3,
  });

  const handleRetry = () => {
    setRetryCount(prev => prev + 1);
    refetch();
  };

  if (error && retryCount < 3) {
    return (
      <Box textAlign='center' p={8}>
        &lt;Text&gt;Something went wrong</Text>
        <Button onClick={handleRetry}>Retry ({retryCount + 1}/3)</Button>
      </Box>
    );
  }

  if (error) {
    return <TableError error={error} />;
  }

  return <DataDisplay data={data} />;
}

Best Practices​

Error Boundary Placement​

  1. Application Level: Wrap entire app for global error catching
  2. Route Level: Wrap major routes for isolated error handling
  3. Component Level: Wrap complex components that might crash
  4. Critical Features: Wrap payment, data entry, and critical operations

Error User Experience​

  1. Clear Messaging: Use user-friendly error messages
  2. Recovery Options: Always provide next steps or recovery actions
  3. Progressive Enhancement: Degrade gracefully when errors occur
  4. Consistent Styling: Use consistent error styling across the app

Error Monitoring​

  1. Sentry Integration: Automatic error reporting and tracking
  2. User Context: Include user and session information
  3. Error Categorization: Categorize errors by type and severity
  4. Performance Impact: Monitor error impact on user experience

Testing Error States​

// Error state testing
describe('Error Components', () => {
  it('should display NotFound for 404 errors', () => {
    render(<NotFound />);
    expect(screen.getByText('Page Not Found')).toBeInTheDocument();
  });

  it('should display PermissionDenied for 403 errors', () => {
    render(<PermissionDenied />);
    expect(screen.getByText('Permission Denied')).toBeInTheDocument();
  });

  it('should handle TableError with various status codes', () => {
    const error = { status: 422, data: { message: 'Validation failed' } };
    render(<TableError error={error} />);
    expect(screen.getByText('Validation failed')).toBeInTheDocument();
  });
});

This comprehensive error handling system provides robust error management and user-friendly fallbacks for all error scenarios in the WorkPayCore Frontend application.