fix: standardise error handling (#7185)

* fix: pass server$ errors through to middleware

* fix e2e tests

* Add changeset

* Add middlewaare error test and remove ErrorResponse

* Update changeset

* Add error handling docs

* Allow returning plain text ServerErrors

* Improvements

* Update docs

* test server errors with text/html accept headers

* Update changesets

* Update ErrorResponse and vite bug url

Author: DustinJSilk

.changeset/furry-paint-spin.md

@@ -0,0 +1,5 @@
+---
+'@builder.io/qwik-city': minor
+---
+
+fix: server$ errors can be caught by @plugin middleware

.changeset/loud-fish-walk.md

@@ -0,0 +1,5 @@
+---
+'@builder.io/qwik-city': minor
+---
+
+refactor: Error types are standardised across server$ functions and routeLoaders

.changeset/quiet-squids-run.md

@@ -0,0 +1,5 @@
+---
+'@builder.io/qwik-city': minor
+---
+
+feat: 499 is now a valid status code

.changeset/tall-flowers-jump.md

@@ -0,0 +1,5 @@
+---
+'@builder.io/qwik-city': minor
+---
+
+fix: server$ functions now correctly throw 4xx errors on the client

packages/docs/src/routes/api/qwik-city-middleware-request-handler/api.json

@@ -327,7 +327,7 @@
         }
       ],
       "kind": "Interface",
-      "content": "```typescript\nexport interface RequestEventCommon<PLATFORM = QwikCityPlatform> extends RequestEventBase<PLATFORM> \n```\n**Extends:** [RequestEventBase](#requesteventbase)<!-- -->&lt;PLATFORM&gt;\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[error](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n(statusCode: ErrorCodes, message: string) =&gt; ErrorResponse\n\n\n</td><td>\n\nWhen called, the response will immediately end with the given status code. This could be useful to end a response with `404`<!-- -->, and use the 404 handler in the routes directory. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Status for which status code should be used.\n\n\n</td></tr>\n<tr><td>\n\n[exit](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n() =&gt; [AbortMessage](#abortmessage)\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[html](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n(statusCode: StatusCodes, html: string) =&gt; [AbortMessage](#abortmessage)\n\n\n</td><td>\n\nConvenience method to send an HTML body response. The response will be automatically set the `Content-Type` header to`text/html; charset=utf-8`<!-- -->. An `html()` response can only be called once.\n\n\n</td></tr>\n<tr><td>\n\n[json](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n(statusCode: StatusCodes, data: any) =&gt; [AbortMessage](#abortmessage)\n\n\n</td><td>\n\nConvenience method to JSON stringify the data and send it in the response. The response will be automatically set the `Content-Type` header to `application/json; charset=utf-8`<!-- -->. A `json()` response can only be called once.\n\n\n</td></tr>\n<tr><td>\n\n[locale](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n(local?: string) =&gt; string\n\n\n</td><td>\n\nWhich locale the content is in.\n\nThe locale value can be retrieved from selected methods using `getLocale()`<!-- -->:\n\n\n</td></tr>\n<tr><td>\n\n[redirect](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n(statusCode: RedirectCode, url: string) =&gt; [RedirectMessage](#redirectmessage)\n\n\n</td><td>\n\nURL to redirect to. When called, the response will immediately end with the correct redirect status and headers.\n\nhttps://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections\n\n\n</td></tr>\n<tr><td>\n\n[send](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\nSendMethod\n\n\n</td><td>\n\nSend a body response. The `Content-Type` response header is not automatically set when using `send()` and must be set manually. A `send()` response can only be called once.\n\n\n</td></tr>\n<tr><td>\n\n[status](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n(statusCode?: StatusCodes) =&gt; number\n\n\n</td><td>\n\nHTTP response status code. Sets the status code when called with an argument. Always returns the status code, so calling `status()` without an argument will can be used to return the current status code.\n\nhttps://developer.mozilla.org/en-US/docs/Web/HTTP/Status\n\n\n</td></tr>\n<tr><td>\n\n[text](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n(statusCode: StatusCodes, text: string) =&gt; [AbortMessage](#abortmessage)\n\n\n</td><td>\n\nConvenience method to send an text body response. The response will be automatically set the `Content-Type` header to`text/plain; charset=utf-8`<!-- -->. An `text()` response can only be called once.\n\n\n</td></tr>\n</tbody></table>",
+      "content": "```typescript\nexport interface RequestEventCommon<PLATFORM = QwikCityPlatform> extends RequestEventBase<PLATFORM> \n```\n**Extends:** [RequestEventBase](#requesteventbase)<!-- -->&lt;PLATFORM&gt;\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[error](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n&lt;T = any&gt;(statusCode: ErrorCodes, message: T) =&gt; [ServerError](#servererror)<!-- -->&lt;T&gt;\n\n\n</td><td>\n\nWhen called, the response will immediately end with the given status code. This could be useful to end a response with `404`<!-- -->, and use the 404 handler in the routes directory. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Status for which status code should be used.\n\n\n</td></tr>\n<tr><td>\n\n[exit](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n() =&gt; [AbortMessage](#abortmessage)\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[html](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n(statusCode: StatusCodes, html: string) =&gt; [AbortMessage](#abortmessage)\n\n\n</td><td>\n\nConvenience method to send an HTML body response. The response will be automatically set the `Content-Type` header to`text/html; charset=utf-8`<!-- -->. An `html()` response can only be called once.\n\n\n</td></tr>\n<tr><td>\n\n[json](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n(statusCode: StatusCodes, data: any) =&gt; [AbortMessage](#abortmessage)\n\n\n</td><td>\n\nConvenience method to JSON stringify the data and send it in the response. The response will be automatically set the `Content-Type` header to `application/json; charset=utf-8`<!-- -->. A `json()` response can only be called once.\n\n\n</td></tr>\n<tr><td>\n\n[locale](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n(local?: string) =&gt; string\n\n\n</td><td>\n\nWhich locale the content is in.\n\nThe locale value can be retrieved from selected methods using `getLocale()`<!-- -->:\n\n\n</td></tr>\n<tr><td>\n\n[redirect](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n(statusCode: RedirectCode, url: string) =&gt; [RedirectMessage](#redirectmessage)\n\n\n</td><td>\n\nURL to redirect to. When called, the response will immediately end with the correct redirect status and headers.\n\nhttps://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections\n\n\n</td></tr>\n<tr><td>\n\n[send](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\nSendMethod\n\n\n</td><td>\n\nSend a body response. The `Content-Type` response header is not automatically set when using `send()` and must be set manually. A `send()` response can only be called once.\n\n\n</td></tr>\n<tr><td>\n\n[status](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n(statusCode?: StatusCodes) =&gt; number\n\n\n</td><td>\n\nHTTP response status code. Sets the status code when called with an argument. Always returns the status code, so calling `status()` without an argument will can be used to return the current status code.\n\nhttps://developer.mozilla.org/en-US/docs/Web/HTTP/Status\n\n\n</td></tr>\n<tr><td>\n\n[text](#)\n\n\n</td><td>\n\n`readonly`\n\n\n</td><td>\n\n(statusCode: StatusCodes, text: string) =&gt; [AbortMessage](#abortmessage)\n\n\n</td><td>\n\nConvenience method to send an text body response. The response will be automatically set the `Content-Type` header to`text/plain; charset=utf-8`<!-- -->. An `text()` response can only be called once.\n\n\n</td></tr>\n</tbody></table>",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/middleware/request-handler/types.ts",
       "mdFile": "qwik-city.requesteventcommon.md"
     },
@@ -411,7 +411,7 @@
         }
       ],
       "kind": "Class",
-      "content": "```typescript\nexport declare class ServerError<T = Record<any, any>> extends Error \n```\n**Extends:** Error\n\n\n<table><thead><tr><th>\n\nConstructor\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[(constructor)(status, data)](#)\n\n\n</td><td>\n\n\n</td><td>\n\nConstructs a new instance of the `ServerError` class\n\n\n</td></tr>\n</tbody></table>\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[data](#servererror-data)\n\n\n</td><td>\n\n\n</td><td>\n\nT\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[status](#servererror-status)\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>",
+      "content": "```typescript\nexport declare class ServerError<T = any> extends Error \n```\n**Extends:** Error\n\n\n<table><thead><tr><th>\n\nConstructor\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[(constructor)(status, data)](#)\n\n\n</td><td>\n\n\n</td><td>\n\nConstructs a new instance of the `ServerError` class\n\n\n</td></tr>\n</tbody></table>\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[data](#servererror-data)\n\n\n</td><td>\n\n\n</td><td>\n\nT\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[status](#servererror-status)\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/middleware/request-handler/error-handler.ts",
       "mdFile": "qwik-city.servererror.md"
     },

packages/docs/src/routes/api/qwik-city-middleware-request-handler/index.md

@@ -1216,7 +1216,7 @@ Description
 
 </td><td>
 
-(statusCode: ErrorCodes, message: string) =&gt; ErrorResponse
+&lt;T = any&gt;(statusCode: ErrorCodes, message: T) =&gt; [ServerError](#servererror)&lt;T&gt;
 
 </td><td>
 
@@ -1465,7 +1465,7 @@ export interface ResolveValue
 ## ServerError
 
 ```typescript
-export declare class ServerError<T = Record<any, any>> extends Error
+export declare class ServerError<T = any> extends Error
 ```
 
 **Extends:** Error

packages/docs/src/routes/docs/(qwikcity)/error-handling/index.mdx

@@ -0,0 +1,112 @@
+---
+title: Error handling | Qwik City
+contributors:
+  - DustinJSilk
+updated_at: '2025-01-11T18:00:00Z'
+created_at: '2025-01-11T18:00:00Z'
+---
+
+# Error handling
+
+When an error is thrown in a loader or `server$` function, a 500 error is returned to the client along with the error. This is useful during development but isn't always desirable for production systems. Qwik provides the tools necessary to customise how errors are handled.
+
+Throwing a `ServerError` instance allows you to return custom errors to the browser with a different status code and serialised data.
+
+> Loaders also provide a helper function on the event object to easily create new ServerErrors.
+
+```tsx
+// Throw ServerErrors from a routerLoader$
+const useProduct = routeLoader$(async (ev) => {
+  const product = await fetch('api/product/1')
+
+  if (!product) {
+    // Throw a 404 with a custom payload
+    throw new ServerError(404, 'Product not found')
+
+    // Or use the existing helper function
+    throw ev.error(404, 'Product not found')
+  }
+
+  return product
+})
+
+// Throw ServerErrors from a server$
+const getPrices = server$(() => {
+  if (!isAuthenticated()) {
+    throw new ServerError(401, { code: 401 })
+  }
+
+  return fetch('api/product/1/prices')
+})
+
+export default component$(() => {
+  const product = useProduct()
+
+  useVisibleTask(() => {
+    getPrices()
+      .then()
+      .catch(err => {
+        // The payload from a ServerError is deserialised as the error caught in the client
+        if (err.code === 401) {
+          // Navigate to login page
+        }
+
+        // Show generic error
+      })
+  })
+
+  return <div>Product page</div>
+})
+```
+
+## Error interceptor
+
+Intercepting errors with middleware has a few usecases: you might want to hide error details in production systems, add structured error logging, or map the error status codes from RPC API calls to HTTP status codes. This is all achieveable with middleware in a `plugin` file.
+
+```tsx
+// src/routes/[email protected]
+import { type RequestHandler } from '@builder.io/qwik-city'
+import { RedirectMessage } from '@builder.io/qwik-city/middleware/request-handler'
+import { isDev } from '@builder.io/qwik/build'
+
+export const onRequest: RequestHandler = async ({ next }) => {
+  try {
+    return await next();
+  } catch (err) {
+    // Pass through 3xx redirects
+    if (isRedirectMessage(err)) {
+      throw err
+    }
+
+    // Pass through ServerErrors
+    if (isServerError(err)) {
+      throw err
+    }
+
+    // Log unknown errors
+    console.error('unknown error', err)
+
+    if (isDev) {
+      throw err
+    } else {
+      throw new ServerError(500, 'Internal server error');
+    }
+  }
+};
+
+function isServerError(err: unknown): err is ServerError {
+  return (
+    err instanceof ServerError ||
+    // This is required for dev environments due to an issue with vite: https://github.com/vitejs/vite/issues/3910
+    (isDev && err instanceof Error && err.constructor.name === "ServerError")
+  );
+}
+
+function isRedirectMessage(err: unknown): err is RedirectMessage {
+  return (
+    err instanceof RedirectMessage ||
+    // This is required for dev environments due to an issue with vite: https://github.com/vitejs/vite/issues/3910
+    (isDev && err instanceof Error && err.constructor.name === "RedirectMessage")
+  );
+}
+```

packages/docs/src/routes/docs/menu.md

@@ -31,6 +31,7 @@
 - [Endpoints](</docs/(qwikcity)/endpoints/index.mdx>)
 - [Middleware](</docs/(qwikcity)/middleware/index.mdx>)
 - [server$](</docs/(qwikcity)/server$/index.mdx>)
+- [Error handling](</docs/(qwikcity)/error-handling/index.mdx>)
 - [Re-exporting loaders](/docs/(qwikcity)/re-exporting-loaders/index.mdx)
 - [Caching](</docs/(qwikcity)/caching/index.mdx>)
 - [HTML attributes](</docs/(qwikcity)/html-attributes/index.mdx>)

packages/qwik-city/src/middleware/request-handler/api.md

@@ -126,8 +126,7 @@ export interface RequestEventBase<PLATFORM = QwikCityPlatform> {
 // @public (undocumented)
 export interface RequestEventCommon<PLATFORM = QwikCityPlatform> extends RequestEventBase<PLATFORM> {
     // Warning: (ae-forgotten-export) The symbol "ErrorCodes" needs to be exported by the entry point index.d.ts
-    // Warning: (ae-forgotten-export) The symbol "ErrorResponse" needs to be exported by the entry point index.d.ts
-    readonly error: (statusCode: ErrorCodes, message: string) => ErrorResponse;
+    readonly error: <T = any>(statusCode: ErrorCodes, message: T) => ServerError<T>;
     // (undocumented)
     readonly exit: () => AbortMessage;
     readonly html: (statusCode: StatusCodes, html: string) => AbortMessage;
@@ -176,7 +175,7 @@ export interface ResolveValue {
 }
 
 // @public (undocumented)
-export class ServerError<T = Record<any, any>> extends Error {
+export class ServerError<T = any> extends Error {
     constructor(status: number, data: T);
     // (undocumented)
     data: T;

packages/qwik-city/src/middleware/request-handler/error-handler.ts

@@ -1,19 +1,20 @@
 /** @public */
-export class ServerError<T = Record<any, any>> extends Error {
+export class ServerError<T = any> extends Error {
   constructor(
     public status: number,
     public data: T
   ) {
-    super();
+    super(typeof data === 'string' ? data : undefined);
   }
 }
 
-export class ErrorResponse extends Error {
+/** @deprecated */
+export class ErrorResponse extends ServerError {
   constructor(
     public status: number,
     message?: string
   ) {
-    super(message);
+    super(status, message);
   }
 }