feat: allow changing response http status code from handleError

.changeset/seven-mangos-cheat.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: allow returning a custom HTTP status code from the `handleError` hook

documentation/docs/30-advanced/20-hooks.md

@@ -185,8 +185,9 @@ If an [unexpected error](errors#Unexpected-errors) is thrown during loading, ren
 
 - you can log the error
 - you can generate a custom representation of the error that is safe to show to users, omitting sensitive details like messages and stack traces. The returned value, which defaults to `{ message }`, becomes the value of `$page.error`.
+- you can customise the status code of the response
 
-For errors thrown from your code (or library code called by your code) the status will be 500 and the message will be "Internal Error". While `error.message` may contain sensitive information that should not be exposed to users, `message` is safe (albeit meaningless to the average user).
+For errors thrown from your code (or library code called by your code) the status will default to 500 and the message will default to "Internal Error". While `error.message` may contain sensitive information that should not be exposed to users, `message` is safe (albeit meaningless to the average user).
 
 To add more information to the `$page.error` object in a type-safe way, you can customize the expected shape by declaring an `App.Error` interface (which must include `message: string`, to guarantee sensible fallback behavior). This allows you to — for example — append a tracking ID for users to quote in correspondence with your technical support staff:
 

packages/kit/src/exports/public.d.ts

@@ -1512,6 +1512,26 @@ export interface RequestEvent<
 	 * You cannot add a `set-cookie` header with `setHeaders` — use the [`cookies`](https://svelte.dev/docs/kit/@sveltejs-kit#Cookies) API instead.
 	 */
 	setHeaders: (headers: Record<string, string>) => void;
+	/**
+	 * Override the status code for error responses. This is useful when you want to customize the HTTP status code returned for an error, for example:
+	 *
+	 *	```js
+	 *	/// file: src/hooks.server.js
+	 *	export async function handleError({ error, event, status, message }) {
+	 *		// Return 503 Service Unavailable for database errors
+	 *		if (error.message.includes('database')) {
+	 *			event.setStatusCode(503);
+	 *		}
+	 *
+	 *		return {
+	 *			message: 'An error occurred'
+	 *		};
+	 *	}
+	 *	```
+	 *
+	 * This method can only be called from the `handleError` hook and only affects error responses.
+	 */
+	setStatusCode: (code: number) => void;
 	/**
 	 * The requested URL.
 	 */

packages/kit/src/runtime/server/page/index.js

@@ -270,7 +270,8 @@ export async function render_page(
 						return redirect_response(err.status, err.location);
 					}
 
-					const status = get_status(err);
+					// Use custom status code if set via event.setStatusCode()
+					const status = event_state.error_status_code ?? get_status(err);
 					const error = await handle_error_and_jsonify(event, event_state, options, err);
 
 					while (i--) {

packages/kit/src/runtime/server/page/respond_with_error.js

@@ -98,7 +98,7 @@ export async function respond_with_error({
 				ssr,
 				csr
 			},
-			status,
+			status: event_state.error_status_code ?? status,
 			error: await handle_error_and_jsonify(event, event_state, options, error),
 			branch,
 			fetched,
@@ -114,10 +114,8 @@ export async function respond_with_error({
 			return redirect_response(e.status, e.location);
 		}
 
-		return static_error_page(
-			options,
-			get_status(e),
-			(await handle_error_and_jsonify(event, event_state, options, e)).message
-		);
+		const status = get_status(e);
+		const error = await handle_error_and_jsonify(event, event_state, options, e);
+		return static_error_page(options, event_state.error_status_code ?? status, error.message);
 	}
 }

packages/kit/src/runtime/server/respond.js

@@ -193,6 +193,14 @@ export async function internal_respond(request, options, manifest, state) {
 				}
 			}
 		},
+		setStatusCode: (code) => {
+			if (typeof code !== 'number' || code < 100 || code > 599) {
+				throw new Error(
+					`Invalid status code: ${code}. Status code must be a number between 100 and 599`
+				);
+			}
+			event_state.error_status_code = code;
+		},
 		url,
 		isDataRequest: is_data_request,
 		isSubRequest: state.depth > 0,

packages/kit/src/runtime/server/utils.js

@@ -84,9 +84,11 @@ export function static_error_page(options, status, message) {
  */
 export async function handle_fatal_error(event, state, options, error) {
 	error = error instanceof HttpError ? error : coalesce_to_error(error);
-	const status = get_status(error);
 	const body = await handle_error_and_jsonify(event, state, options, error);
 
+	// Use custom status code if set via event.setStatusCode()
+	const status = state.error_status_code ?? get_status(error);
+
 	// ideally we'd use sec-fetch-dest instead, but Safari — quelle surprise — doesn't support it
 	const type = negotiate(event.request.headers.get('accept') || 'text/html', [
 		'application/json',

packages/kit/src/types/internal.d.ts

@@ -611,6 +611,8 @@ export interface RequestState {
 	remote_data?: Map<RemoteInfo, Record<string, MaybePromise<any>>>;
 	refreshes?: Record<string, Promise<any>>;
 	is_endpoint_request?: boolean;
+	/** Custom status code set by event.setStatusCode() */
+	error_status_code?: number;
 }
 
 export interface RequestStore {

packages/kit/src/utils/error.js

@@ -25,9 +25,22 @@ export function normalize_error(error) {
 
 /**
  * @param {unknown} error
+ * @returns {number}
  */
 export function get_status(error) {
-	return error instanceof HttpError || error instanceof SvelteKitError ? error.status : 500;
+	if (error instanceof HttpError || error instanceof SvelteKitError) {
+		return error.status;
+	}
+	// For overrides / custom error objects
+	if (
+		typeof error === 'object' &&
+		error !== null &&
+		'status' in error &&
+		typeof error.status === 'number'
+	) {
+		return error.status;
+	}
+	return 500;
 }
 
 /**

packages/kit/test/apps/basics/src/hooks.server.js

@@ -57,6 +57,10 @@ export const handleError = ({ event, error: e, status, message }) => {
 		message = ev.locals.message;
 	}
 
+	if (event.url.pathname.startsWith('/errors/custom-error')) {
+		event.setStatusCode(422);
+	}
+
 	return event.url.pathname.endsWith('404-fallback')
 		? undefined
 		: { message: `${error.message} (${status} ${message})` };

packages/kit/test/apps/basics/src/routes/errors/custom-error/+server.js

@@ -0,0 +1,6 @@
+/**
+ * This gets intercepted by the handleError hook and sets the status code to 422
+ */
+export function GET() {
+	throw new Error('Custom error');
+}

packages/kit/test/apps/basics/test/server.test.js

@@ -452,6 +452,11 @@ test.describe('Errors', () => {
 		expect(await response.text()).toMatch('thisvariableisnotdefined is not defined');
 	});
 
+	test('handleError hook can set the response status', async ({ request }) => {
+		const response = await request.get('/errors/custom-error');
+		expect(response.status()).toBe(422);
+	});
+
 	test('returns 400 when accessing a malformed URI', async ({ page }) => {
 		const response = await page.goto('/%c0%ae%c0%ae/etc/passwd');
 		if (process.env.DEV) {

packages/kit/types/index.d.ts

@@ -1488,6 +1488,26 @@ declare module '@sveltejs/kit' {
 		 * You cannot add a `set-cookie` header with `setHeaders` — use the [`cookies`](https://svelte.dev/docs/kit/@sveltejs-kit#Cookies) API instead.
 		 */
 		setHeaders: (headers: Record<string, string>) => void;
+		/**
+		 * Override the status code for error responses. This is useful when you want to customize the HTTP status code returned for an error, for example:
+		 *
+		 *	```js
+		 *	/// file: src/hooks.server.js
+		 *	export async function handleError({ error, event, status, message }) {
+		 *		// Return 503 Service Unavailable for database errors
+		 *		if (error.message.includes('database')) {
+		 *			event.setStatusCode(503);
+		 *		}
+		 *
+		 *		return {
+		 *			message: 'An error occurred'
+		 *		};
+		 *	}
+		 *	```
+		 *
+		 * This method can only be called from the `handleError` hook and only affects error responses.
+		 */
+		setStatusCode: (code: number) => void;
 		/**
 		 * The requested URL.
 		 */