Next.js API 라우트에서 413을 만났을 때 요청 크기부터 재본 기록

증상은 저장 버튼을 누른 뒤에만 나타났다

관리자에서 긴 본문을 저장할 때만 413 Request Entity Too Large가 나왔다. 처음에는 에디터의 이미지 데이터가 원인이라고 생각했지만, 이미지 없이 코드 예시를 여러 개 붙여도 재현됐다. 브라우저 개발자 도구 Network 탭에서 요청의 Request Payload 크기를 보니 약 1.3MB였다.

어디에서 막히는지 나눠 확인했다

응답 헤더에 server: nginx가 있어 Next.js 코드보다 Nginx를 먼저 확인했다. 임시로 작은 JSON과 큰 JSON을 각각 보내고 access/error 로그의 시간을 맞췄다.

curl -i -X POST https://example.com/api/posts   -H 'content-type: application/json'   --data-binary @large-post.json
sudo tail -f /var/log/nginx/error.log

에러 로그에 client intended to send too large body가 남으면 애플리케이션까지 요청이 도달하지 않은 것이다. 이 경우 API 핸들러에 로그를 더 넣어도 답이 없다.

설정을 올리되 무제한으로 열지는 않았다

게시글 본문에 필요한 최대치를 생각해 5MB로 정했다. 업로드 파일은 별도 스토리지 경로로 보내고, 일반 JSON API를 크게 열어 두지 않기로 했다.

server {
  client_max_body_size 5m;

  location / {
    proxy_pass http://127.0.0.1:3000;
  }
}

sudo nginx -t
sudo systemctl reload nginx

Next.js의 서버 액션이나 별도 body parser를 쓰는 구조라면 그 제한도 따로 확인해야 한다. Nginx만 바꾸고 끝났다고 생각했다가, 다른 경로에서는 여전히 작은 제한에 걸릴 수 있다.

다음에 바로 볼 체크포인트

• Network 탭에서 실제 전송 바이트를 확인한다.
• 응답 헤더와 프록시 에러 로그로 차단 위치를 판단한다.
• 본문 JSON과 파일 업로드의 한도를 분리한다.
• 설정 변경 뒤 작은 요청과 경계 크기 요청을 모두 테스트한다.

413은 서버가 고장 났다는 뜻보다 약속한 크기 제한을 넘었다는 신호에 가깝다. 숫자를 재고 어느 레이어가 거절했는지 찾으니 수정 범위가 훨씬 작아졌다.