graph TD
    A[Server Response] --> B[Middleware Security Check]
    B --> C[ApiClient Processing]
    C --> D[Error Handler Analysis]
    D --> E[Enhanced Error Details]
    E --> F[Single Toast Notification]
    E --> G[Error Display Component]
    F --> H[User Sees Beautiful Error]
    G --> H

// This is how we handle SANITIZATION_FAILED errors
private getSanitizationErrorDetails(response: ApiErrorResponse): ErrorDetails {
  const security = response.security;
  const violations = security?.violations || [];
  const warnings = security?.warnings || [];
  
  // Build detailed description from violations
  let description = 'Our security system detected potentially harmful content in your request.';
  if (violations.length > 0) {
    description += `

Detected issues:
• ${violations.join('
• ')}`;
  }
  
  return {
    title: 'Invalid Request Content',
    message: 'Your request contains potentially harmful content',
    description,
    action: 'Please review your input, remove any suspicious content, and try again',
    severity: 'error',
    code: 'SANITIZATION_FAILED'
  };
}

// Enhanced notifications with detailed descriptions
showNotification.enhanced.error(
  'Security Token Issue',
  'Your security token has expired',
  'This happens when your session expires or security tokens become invalid. We'll automatically refresh your token and retry.',
  'Please wait while we refresh your security token...'
);

// Smart error handling with automatic retry
if (response.status === 403 && isCSRFError(errorData)) {
  if (attempt === 1) {
    const tokenResult = await csrfClient.generateCSRFToken();
    if (tokenResult.success) {
      continue; // Retry the request
    }
  }
  // Return enhanced error details
  return {
    success: false,
    error: errorDetails.message,
    details: errorDetails
  };
}

{
  "success": false,
  "error": "Request contains malicious content and has been blocked",
  "code": "SANITIZATION_FAILED",
  "security": {
    "violations": [
      "Headers: Dangerous pattern detected: /<script/i",
      "Headers: String length exceeds maximum (1268 > 1000)"
    ],
    "warnings": [
      "Headers: Suspicious pattern detected: /eval\(/i"
    ]
  }
}

// Extracts specific values from security response
const violations = security?.violations || [];
const warnings = security?.warnings || [];

// Builds detailed description
let description = 'Our security system detected potentially harmful content in your request.';
if (violations.length > 0) {
  description += `

Detected issues:
• ${violations.join('
• ')}`;
}

// Enhanced error display with dropdown functionality
function ErrorDisplay({ error, onDismiss }: { error: ErrorDetails; onDismiss: () => void }) {
  const [isExpanded, setIsExpanded] = useState(false);
  const hasDetails = error.description || error.action;
  
  return (
    <motion.div className={`${severityStyles[error.severity]} border rounded-xl`}>
      <div onClick={hasDetails ? () => setIsExpanded(!isExpanded) : undefined}>
        <div className="font-semibold">{error.title}</div>
        <div className="text-sm opacity-90">{error.message}</div>
        {hasDetails && (
          <div className="flex items-center gap-2">
            <InfoIcon className="w-4 h-4 opacity-60" />
            {isExpanded ? <ChevronUpIcon /> : <ChevronDownIcon />}
          </div>
        )}
      </div>
      
      {isExpanded && (
        <div className="animate-in slide-in-from-top-2">
          {error.description && (
            <div>
              <h5>Description:</h5>
              <p className="whitespace-pre-line">{error.description}</p>
            </div>
          )}
          {error.action && (
            <div>
              <h5>Action Required:</h5>
              <p>{error.action}</p>
            </div>
          )}
        </div>
      )}
    </motion.div>
  );
}

// Enhanced CSRF protection with detailed error responses
if (path.startsWith('/api/') && !path.startsWith('/api/internal/csrf')) {
  const csrfResult = await handleCSRFProtection(req);
  if (!csrfResult.allowed) {
    const response = NextResponse.json({
      success: false,
      error: csrfResult.error,
      ref: requestId,
      security: {
        type: 'csrf_protection',
        status: csrfResult.status
      }
    }, { status: 403 });
    return withSecurityHeaders(response, isHttps);
  }
}

// Detailed violation reporting
const violations: string[] = [];
const warnings: string[] = [];

// Check for dangerous patterns
for (const pattern of this.dangerousPatterns) {
  if (pattern.test(str)) {
    violations.push(`${context}: Dangerous pattern detected: ${pattern.source}`);
  }
}

return {
  isValid: violations.length === 0,
  sanitizedData,
  violations,
  warnings
};

// ApiClient notifications disabled
const response = await ApiClient.getVideoInfo(extractedUrl, {
  showNotifications: false // Prevents duplicate toasts
});

// Only hook shows notification
showNotification.enhanced.fromErrorDetails(response.details);

// Handle API errors with enhanced details
const response = await ApiClient.getVideoInfo(url);
if (!response.success && response.details) {
  // response.details contains:
  // - title: "Invalid Request Content"
  // - message: "Your request contains potentially harmful content"
  // - description: "Our security system detected..."
  // - action: "Please review your input..."
  // - severity: "error"
  // - code: "SANITIZATION_FAILED"
  
  setError(response.details);
  showNotification.enhanced.fromErrorDetails(response.details);
}