Custom error response from collection access control

[Fitch24]

In Payload v2, I could throw an APIError (or custom errors inheriting from the APIError class) with a custom status code and message. For example, I could return a 401 status for unauthenticated users, 403 if the user lacked the required permissions, or 404 to hide certain resources from specific users.

However, after migrating to Payload v3, throwing errors in a collection access hook breaks the admin panel. This happens because the admin panel calls each access hook to determine user permissions for each operation in every collection, and the Next.js app crashes if any error is thrown (though REST API requests still work as expected, like in v2).

Currently, I’ve solved this problem by creating a wrapper around the access function:

import {
  APIError,
  type Access,
  type AccessArgs,
  type AccessResult,
  type CollectionConfig,
  type PayloadRequest,
} from "payload";

// Checks if `req` is an internal Payload access check (from the admin panel)
const isAccessCheck = (req: PayloadRequest) => {
  if (req.payloadAPI === "local") {
    return req.pathname === "/" || req.pathname.startsWith("/admin");
  }
  return req.pathname === "/api/access";
};

// Wraps the 'access' function to make it safe when invoked from the admin panel
export const collectionAccess: (access: Access) => Access = (access) => {
  if (typeof access !== "function") {
    throw new Error("'access' must be a function");
  }

  return async (args: AccessArgs) => {
    try {
      return await access(args);
    } catch (error) {
      if (isAccessCheck(args.req)) {
        return false;
      }
      throw error;
    }
  };
};

// Usage example
export const posts: CollectionConfig = {
  slug: "posts",
  fields: [
    {
      name: "title",
      type: "text",
      required: true,
    },
    {
      name: "content",
      type: "text",
      required: true,
    },
  ],
  access: {
    create: collectionAccess((args) => {
      if (!args.req.user) {
        throw new APIError("Authorization required!", 401);
      }
      return true;
    }),
  },
};

But maybe it would be better to have some built-in functionality for this use case — for example, the ability to detect whether an access hook (or even the entire req) was invoked from the admin panel?