[Docs]: It is unclear how to return errors from server-side Resource Routes

[apike]

Describe what's incorrect/missing in the documentation

The doc for Resource Routes encourages you to return a Response.json from a REST/resource endpoint, but only shows the happy path.

If you return a Response.json with { status: 500 }, it sort of works but error reporting doesn't work – that is, the central handleError in entry.server.tsx doesn't fire.

This, plus the fact Remix tended towards having you throw errors, makes it seem like you are not supposed to return an error from a resource route.

However, the Error Boundaries doc says:

It's not recommended to intentionally throw errors to force the error boundary to render as a means of control flow. ... This is not just for loaders, but for all route module APIs: loaders, actions, components, headers, links, and meta.

And the Status Codes doc advises you to "Set status codes from loaders and actions with data.", with this example returning a 4xx error inside an action:

    return data(
      { message: "Invalid title" },
      { status: 400 }
    );

These make it seem like you are supposed to return an error, but meanwhile, there's also similar but different format in the Error Boundaries doc showing a throw under the title Throw data in loaders/actions:

    throw data("Record Not Found", { status: 404 });

Since the above is in the Error Boundaries doc, it's not clear this is applicable to resource routes, since I believe resource routes do not render within an Error Boundary.

So, in short, can we get clear & consistent documentation on how we're meant to return a 4xx or 5xx error from an resource route's action?