refactor: replace generic Error('Unauthorized') with UnauthorizedError (#14879)

Refactors all auth checks to throw `UnauthorizedError` instead of the
generic `Error('Unauthorized')`. This ensures consistent unauthorized
errors being thrown

Author: AlessioGr

docs/local-api/server-functions.mdx

@@ -512,9 +512,11 @@ Using server functions helps prevent direct exposure of Local API operations to
 Example of restricting access based on user role:
 
 ```ts
+import { UnauthorizedError } from 'payload'
+
 export async function deletePost(postId, user) {
   if (!user || user.role !== 'admin') {
-    throw new Error('Unauthorized')
+    throw new UnauthorizedError()
   }
 
   const payload = await getPayload({ config })

packages/payload/src/utilities/canAccessAdmin.ts

@@ -1,5 +1,7 @@
 import type { PayloadRequest } from '../types/index.js'
 
+import { UnauthorizedError } from '../errors/UnauthorizedError.js'
+
 /**
  * Protects admin-only routes, server functions, etc.
  * The requesting user must either:
@@ -19,11 +21,11 @@ export const canAccessAdmin = async ({ req }: { req: PayloadRequest }) => {
       const canAccess = await adminAccessFn({ req })
 
       if (!canAccess) {
-        throw new Error('Unauthorized')
+        throw new UnauthorizedError()
       }
       // Match the user collection to the global admin config
     } else if (adminUserSlug !== incomingUserSlug) {
-      throw new Error('Unauthorized')
+      throw new UnauthorizedError()
     }
   } else {
     const hasUsers = await req.payload.find({
@@ -35,7 +37,7 @@ export const canAccessAdmin = async ({ req }: { req: PayloadRequest }) => {
 
     // If there are users, we should not allow access because of `/create-first-user`
     if (hasUsers.docs.length) {
-      throw new Error('Unauthorized')
+      throw new UnauthorizedError()
     }
   }
 }

packages/ui/src/forms/fieldSchemasToFormState/serverFunctions/renderFieldServerFn.ts

@@ -1,4 +1,10 @@
-import { deepMerge, type Field, type FieldState, type ServerFunction } from 'payload'
+import {
+  deepMerge,
+  type Field,
+  type FieldState,
+  type ServerFunction,
+  UnauthorizedError,
+} from 'payload'
 
 import { getClientConfig } from '../../../utilities/getClientConfig.js'
 import { getClientSchemaMap } from '../../../utilities/getClientSchemaMap.js'
@@ -44,7 +50,7 @@ export const _internal_renderFieldHandler: ServerFunction<
   // eslint-disable-next-line @typescript-eslint/require-await
 > = async ({ field: fieldArg, initialValue, path, req, schemaPath }) => {
   if (!req.user) {
-    throw new Error('Unauthorized')
+    throw new UnauthorizedError()
   }
 
   const [entityType, entitySlug, ...fieldPath] = schemaPath.split('.')

packages/ui/src/utilities/buildFormState.ts

@@ -7,7 +7,7 @@ import type {
   ServerFunction,
 } from 'payload'
 
-import { canAccessAdmin, formatErrors } from 'payload'
+import { canAccessAdmin, formatErrors, UnauthorizedError } from 'payload'
 import { getSelectMode, reduceFieldsToValues } from 'payload/shared'
 
 import { fieldSchemasToFormState } from '../forms/fieldSchemasToFormState/index.js'
@@ -70,7 +70,7 @@ export const buildFormStateHandler: ServerFunction<
     }
 
     if (err.message === 'Unauthorized') {
-      throw new Error('Unauthorized')
+      throw new UnauthorizedError()
     }
 
     return formatErrors(err)