PERS Error Handling

{
  "status": 404,
  "title": "Resource Not Found",
  "detail": "User with ID 12345 could not be found",
  "message": "The requested user could not be found",
  "code": "USER_NOT_FOUND",
  "category": "DOMAIN_RULE",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "correlationId": "pers-abc123-def456",
  "retryable": false,
  "domain": "user"
}

import type { StructuredError, ErrorCategory } from '@explorins/pers-shared';

{
  "status": 401,
  "title": "Authentication Required",
  "detail": "Valid authentication credentials are required",
  "message": "Please log in to access this resource",
  "code": "AUTHENTICATION_REQUIRED",
  "category": "SECURITY",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "correlationId": "pers-def456-ghi789",
  "retryable": false
}

{
  "status": 400,
  "title": "Validation Error",
  "detail": "The email field is required",
  "message": "The email field is required",
  "code": "VALIDATION_ERROR",
  "category": "VALIDATION",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "correlationId": "pers-jkl012-mno345",
  "details": {
    "field": "email",
    "rejectedValue": null
  },
  "retryable": false
}

// Example: Handling API errors in JavaScript/TypeScript
async function callAPI() {
  try {
    const response = await fetch('/api/users', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer your-token',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ name: 'John' })
    });
    
    if (!response.ok) {
      const error = await response.json();
      
      // Handle different error categories
      if (error.category === 'SECURITY') {
        // Redirect to login
        window.location.href = '/login';
      } else if (error.category === 'VALIDATION') {
        // Show validation errors to user
        showValidationError(error.details);
      } else {
        // Show generic error message
        showErrorMessage(error.message);
      }
      return;
    }
    
    const data = await response.json();
    // Handle success response
  } catch (networkError) {
    // Handle network errors
    showErrorMessage('Network error. Please try again.');
  }
}

import type { 
  ValidationStructuredError,
  DomainRuleStructuredError,
  SecurityStructuredError,
  RateLimitStructuredError
} from '@explorins/pers-shared';

// Validation errors include field violations
interface ValidationStructuredError {
  category: 'VALIDATION';
  details: {
    violations: Array<{
      field: string;
      code: string;
      message: string;
      rejectedValue?: any;
    }>;
  };
  target: string; // Required field
  retryable: false;
}

// Rate limit errors include quota information
interface RateLimitStructuredError {
  category: 'RATE_LIMIT';
  details: {
    limit: number;
    remaining: number;
    resetTime: string; // ISO 8601
    window: string; // e.g., "1h", "1d"
  };
  retryable: true;
}