Корректный ответ JSON 404 в Next.js для несуществующих API

В Next.js при использовании App Router есть одна неприятная особенность: если пользователь обращается к несуществующему API-роуту, вместо аккуратного JSON с ошибкой возвращается HTML-страница из not-found.tsx. Для API это неудобно — клиенты ожидают получить структурированный JSON, а не HTML.

Проблема

Пример структуры:

/app/api/user/route.ts

• GET /api/user — всё работает корректно.
• GET /api — возвращается HTML из /app/not-found.tsx 😦
• GET /api/anything/else — снова HTML 😦

Решение — универсальный catch-all роут

Next.js поддерживает "catch-all" маршруты, которые можно использовать для перехвата всех несуществующих API-запросов. Это позволяет элегантно возвращать JSON с ошибкой 404 без костылей и лишних проверок.

1. Создаём файл для перехвата всех несуществующих API-роутов

Добавьте файл:

/app/api/[...not_found]/route.ts

Пример содержимого:

// Обработка GET-запросов
export async function GET() {
  return Response.json({ error: 'Not Found' }, { status: 404 });
}

// Обработка POST-запросов
export async function POST() {
  return Response.json({ error: 'Not Found' }, { status: 404 });
}

// При необходимости добавьте другие методы (PUT, DELETE и т.д.)

2. Перехват запроса к /api

Запросы к /api (без вложенных путей) не попадут в [...not_found], поэтому нужен отдельный файл:

/app/api/route.ts

Пример содержимого:

export async function GET() {
  return Response.json({ error: 'Not Found' }, { status: 404 });
}

3. Как это работает

Используйте catch-all роуты в Next.js, чтобы ваши API всегда возвращали корректный JSON с ошибкой 404 для несуществующих путей. Это просто, нативно и удобно для клиентов.