Next.js API 404와 405, 주소 오류인지 메서드 오류인지 나누는 법

Next.js 화면은 열리는데 저장이나 로그인 요청만 404 또는 405로 실패하면 API 코드를 전부 다시 만들기 쉽다. 먼저 할 일은 더 많은 파일을 고치는 것이 아니다. 실패한 요청의 URL·method·status를 적고, 요청 주소와 route 경로 또는 요청 method와 exported 함수를 각각 비교하는 것이다.

404는 서버가 요청한 리소스를 찾지 못했다는 뜻이고, 405는 대상 리소스가 그 요청 메서드를 지원하지 않는다는 뜻이다. Next.js App Router에서는 이 차이를 이용해 첫 점검을 나눌 수 있다. 404면 주소와 route 위치, 405면 요청 method와 함수 이름부터 본다. 다만 상태 코드만으로 모든 원인을 확정할 수는 없다. rewrite, proxy, 인증 계층, 배포 설정이 같은 코드를 반환할 수도 있다.

Tap to zoom

404와 405는 첫 확인 지점이 다릅니다

Route Handlers (Next.js)는 App Router의 요청 처리기를 app 디렉터리 안 route.js 또는 route.ts로 정의한다고 설명한다. GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS를 지원하며, 해당 route가 지원하지 않는 메서드가 호출되면 Next.js는 405를 반환한다.

404 Not Found (MDN Web Docs)와 405 Method Not Allowed (MDN Web Docs)를 함께 보면 판단 기준이 선명해진다.

이 표는 원인 확정표가 아니라 첫 조사 방향을 고르는 표다. 404인데 route 파일이 정확히 있거나 405인데 함수도 맞다면, 그다음에는 실제 응답 서버와 rewrite, proxy, 인증 처리를 확인한다.

Network에서 요청 세 줄을 적습니다

브라우저 개발자 도구의 Network 탭을 열고 실패한 요청 하나를 선택한다. 긴 에러 문장보다 아래 세 값을 먼저 복사한다.

Request URL: https://example.com/api/save
Request Method: POST
Status Code: 404 또는 405

Network 목록에 비슷한 요청이 여러 개라면 버튼을 한 번만 누른 뒤 새로 생긴 항목을 고른다. 요청이 아예 생기지 않는다면 API route보다 클릭 이벤트나 폼 제출 코드부터 봐야 한다. API 요청은 생기지만 실패한다면 URL과 method를 기준으로 다음 점검으로 넘어간다.

AI에게 오류를 전달할 때도 이 세 줄이 출발점이다. 스택 전체를 붙이기 전에 재현한 요청 하나를 고정하면 수정 범위가 줄어든다. 콘솔과 Network에서 무엇을 복사할지 더 필요하다면 AI에게 다시 질문할 오류 네 칸을 함께 확인할 수 있다.

Tap to zoom

route 경로와 exported 함수를 따로 맞춥니다

404는 URL 조각을 폴더 경로와 비교합니다

요청이 /api/save라면 App Router의 첫 후보는 다음 경로다.

요청 URL: /api/save
파일 후보: app/api/save/route.ts

요청이 /api/posts/create라면 폴더 조각도 같은 순서로 늘어난다.

요청 URL: /api/posts/create
파일 후보: app/api/posts/create/route.ts

app/api/save.ts와 app/api/save/route.ts는 다르다. 현재 route.js 파일 규칙 (Next.js)은 route 파일을 해당 경로 segment 안에 두고, 동적 경로도 app/items/[slug]/route.ts처럼 구성하는 예를 제공한다.

상대 주소도 확인한다. fetch("api/save")는 현재 페이지 경로에 따라 예상과 다른 URL이 될 수 있다. 같은 사이트의 App Router handler를 부르는 입문 예제라면 Network에 찍힌 실제 URL을 보고, 의도한 값이 /api/save인지 확인한다.

405는 요청 method와 함수 이름을 비교합니다

화면 코드가 POST를 보내면 해당 route 파일에는 POST라는 named export가 필요하다.

await fetch("/api/save", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(form),
});

export async function POST(request: Request) {
  const data = await request.json();
  return Response.json({ ok: true, data });
}

route 파일에 GET만 있는데 브라우저가 POST를 보내면 405의 첫 후보가 된다. 여기서는 함수 내부 로직을 고치기 전에 Network의 Request Method와 route 파일의 대문자 함수 이름이 같은지 확인한다. POST를 추가한 뒤에는 같은 요청을 다시 보내 status가 바뀌었는지 본다.

배포 주소와 브라우저 공개값을 분리합니다

로컬에서는 되지만 공개 사이트에서만 404가 난다면 Request URL에 localhost가 남았는지 확인한다. 공개 페이지에서 http://localhost:3000/api/save를 호출하면 배포 서버의 route가 아니라 방문자의 컴퓨터를 가리킨다. 같은 origin의 handler라면 /api/save 같은 상대 경로가 배포 환경 차이를 줄인다.

외부 API 기본 주소가 필요할 때는 환경변수의 공개 범위를 구분한다. Environment Variables (Next.js)는 NEXT_PUBLIC_ 접두사가 붙은 값을 빌드 때 브라우저 JavaScript에 포함할 수 있다고 설명한다. 이 접두사는 보안 장치가 아니다. 브라우저에 보여도 되는 URL만 공개 변수로 두고 API 키와 서버 비밀값은 넣지 않는다. 환경변수 이름과 노출 범위를 더 점검하려면 Next.js 환경변수의 공개값과 서버값 구분을 참고할 수 있다.

AI에는 아래처럼 한 요청과 관련 파일만 전달한다.

Next.js App Router에서 아래 요청이 실패한다.

Request URL: [Network의 실제 URL]
Request Method: [GET/POST/...]
Status Code: [404/405]
호출 코드: [fetch가 있는 10~20줄]
route 파일 경로: [실제 경로 또는 없음]
route 파일의 exported 함수: [GET/POST/... 또는 없음]

404면 URL과 route 경로를 먼저 비교하고,
405면 Request Method와 exported 함수 이름을 먼저 비교해라.
다른 구조로 바꾸지 말고 관련 파일 두 개 안에서 최소 수정안을 제시해라.
수정 뒤 같은 요청에서 확인할 URL, method, status도 적어라.

파일 두 개 제한은 기술 규칙이 아니라 과잉 수정을 막는 작업 제약이다. 조사 결과 proxy나 인증 계층이 원인이라면 범위를 넓혀야 한다. 먼저 한 요청으로 가설을 확인한 뒤 넓힌다.

같은 요청을 다시 실행해 끝냅니다

수정 전후를 비교하려면 아래 다섯 줄을 채운다.

실제 Request URL:
Request Method:
수정 전 Status Code:
예상 route 파일과 함수:
수정 후 Status Code와 응답:

404였다면 실제 URL과 route 경로가 맞아졌는지 확인한다. 405였다면 요청 method를 처리하는 함수와 응답의 Allow 헤더를 함께 볼 수 있다. 수정 뒤에는 같은 버튼과 같은 입력으로 요청을 다시 보내야 비교가 된다. 다른 기능까지 동시에 바꾸면 어느 수정이 효과가 있었는지 알 수 없다.

확인한 공식 문서

• Route Handlers (Next.js)
• route.js 파일 규칙 (Next.js)
• Environment Variables (Next.js)
• 404 Not Found (MDN Web Docs)
• 405 Method Not Allowed (MDN Web Docs)

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.