Request: Built-in support for returning HTTP 503 in Next.js App Router #77342

yuyake0084 · 2025-03-20T16:26:59Z

yuyake0084
Mar 20, 2025

Goals

Provide a built-in way to return an HTTP 503 response in Next.js.
Allow developers to indicate service unavailability in a standardized way.
Improve handling of maintenance mode or temporary downtime in Next.js applications.

Background

I am building a service that displays various types of content. Many content holders manage their own content, and in some cases, they may temporarily choose to hide their content details.

In such cases, a separate system's API responds with an HTTP 503 status. Ideally, Next.js should also return a 503 response to crawlers when it receives this status. However, in the App Router, there is no built-in way to return an HTTP 503 status. Currently, if an internal 5xx error occurs, Next.js automatically returns a 500 status, which is not always appropriate.

For SEO and proper indexing, it is important to return a 503 status instead of 500 when content is temporarily unavailable due to the content holder's decision. However, there is no straightforward way to achieve this in the App Router. I have explored several potential solutions, but none of them provide an optimal approach.

Attempted Solutions

To solve this issue, I have considered various approaches, but ultimately, I found only two possible solutions:

1. Use `middleware.ts` with Node.js runtime

The middleware can call an external API and return a response based on the status code.
Since middleware runs separately from the SSR process, Request Memoization does not work, meaning the API is called twice, increasing the server load.

// middleware.tsx
export async function middleware() {
    try {
        // Call API...
    } catch (error) {
        if (error instanceof ServiceTemporarilyUnavailableError) {
            const { renderToString } = await import("react-dom/server");
            const html = renderToString(
                <html>
                    <head>
                        <meta charSet="utf-8" />
                        <meta name="viewport" content="width=device-width, initial-scale=1" />
                    </head>
                    <body>
                        503
                    </body>
                </html>
            );

            return new NextResponse(html, {
                status: 503,
                headers: { "Content-Type": "text/html" },
            });
        }
    }
    return NextResponse.next();
}

2. Switch to the Pages Router

Unlike the App Router, the Pages Router allows more flexibility in setting status codes.
However, rewriting the existing App Router codebase to the Pages Router is a significant cost.

// pages/hoge/index.tsx
export const getServerSideProps: GetServerSideProps = async ({ res, query }) => {
    try {
        // Call API...
        return {};
    } catch (error) {
        if (error instanceof ServiceTemporarilyUnavailableError) {
            res.statusCode = 503;
            throw error;
        }
    }

    return { props: {} };
};

Both solutions have drawbacks: middleware increases API load, while switching to the Pages Router requires rewriting a significant portion of the application.

Feature Request

I would like Next.js to provide a built-in way to return an HTTP 503 status in the App Router. This would help handle temporary content unavailability in a more efficient and SEO-friendly way, without the need for workarounds that introduce additional complexity or performance overhead.

Proposal

I propose introducing an experimental feature similar to authInterrupts, such as serverErrorInterrupts. This would allow developers to enable enhanced server-side error handling, including the ability to return HTTP 503 responses in the App Router.

// e.g.
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    serverErrorInterrupts: true,
  },
}

export default nextConfig

In addition, providing a function like serviceUnavailable() that sets a 503 status while rendering error.tsx would be extremely useful. This would allow developers to properly return a 503 status inside Server Components without complex workarounds.

import { serviceUnavailable } from 'next/navigation';

export default async function Page({ searchParams }: Props) {
  try {
    // Call API...
    const { data } = await fetch('...');

    return (
      <>
        {data?.hoge}
      </>
    );
  } catch (error) {
    if (error instanceof ServiceTemporarilyUnavailableError) {
      // Return 503 status!
      serviceUnavailable();
    }

    throw error;
  }
}

References

Alternative Solutions

If there is a simpler way to achieve this without introducing a new experimental feature, I would love to hear about it!
I appreciate your feedback and guidance.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Request: Built-in support for returning HTTP 503 in Next.js App Router #77342

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Request: Built-in support for returning HTTP 503 in Next.js App Router #77342

Uh oh!

Uh oh!

yuyake0084 Mar 20, 2025

Goals

Background

Attempted Solutions

1. Use middleware.ts with Node.js runtime

2. Switch to the Pages Router

Feature Request

Proposal

References

Alternative Solutions

Replies: 0 comments

yuyake0084
Mar 20, 2025

1. Use `middleware.ts` with Node.js runtime