404 Not Found vs 500 에러 차이와 원인 — 어디가 잘못됐나

증상: 404 Not Found vs 500 Internal Server Error

브라우저나 API 응답에서 자주 보는 두 숫자입니다.

404 Not Found
500 Internal Server Error

가장 먼저 알아야 할 것은 앞자리 숫자입니다. 4xx는 클라이언트(요청) 쪽 문제, 5xx는 서버 쪽 문제를 뜻합니다. 즉 404는 "네가 없는 걸 찾았다", 500은 "내(서버)가 처리하다 터졌다"입니다.

404 Not Found — 왜 나는가

• URL 오타·경로 불일치 — /users인데 /user로 요청.
• 라우트 미정의 — 서버에 해당 엔드포인트가 없음.
• 메서드 불일치 일부 케이스 — 라우트는 있지만 GET만 있고 POST는 없음(405가 정석이나 404로 처리되기도).
• 정적 파일 경로 오류 — 빌드 산출물·이미지 경로가 틀림.
• SPA 새로고침 — 클라이언트 라우팅인데 서버에 fallback 설정이 없음.

404 해결

404는 대개 "요청 URL"과 "서버 라우트 정의"를 글자 그대로 대조하면 풀립니다. 네트워크 탭에서 실제로 나간 URL을 복사해 서버 코드의 라우트와 비교하세요. prefix(/api), 끝 슬래시, 대소문자, HTTP 메서드 네 가지를 차례로 점검하면 거의 다 잡힙니다.

# URL과 라우트 정의를 대조
app.get('/api/users', handler)   // 경로·메서드 일치 확인

# SPA 새로고침 404: 모든 경로를 index.html로 fallback
app.get('*', (req,res)=>res.sendFile('index.html'))

SPA(React Router 등)에서 특정 페이지를 새로고침하면 404가 나는 건, 서버가 그 경로를 모르기 때문입니다. 위처럼 fallback 라우트를 두면 클라이언트 라우터가 경로를 처리하게 됩니다.

500 Internal Server Error — 왜 나는가

500은 "서버 코드가 처리 중 예외로 죽었다"는 포괄적 신호입니다. 화면에는 자세한 게 안 나오니 서버 로그를 봐야 합니다.

• 코드 예외 — null 참조, undefined 접근, 타입 오류.
• DB 연결 실패 — 커넥션 정보 오류, DB 다운.
• 환경변수 누락 — 키·시크릿이 비어 있음.
• 외부 API 실패의 미처리 — try/catch 없이 throw.
• JSON 파싱 / 잘못된 입력 처리 누락.

500 해결

# 핵심: 서버 로그를 본다
# Node 예시
app.use((err, req, res, next) => {
  console.error(err.stack);      // 진짜 원인은 여기
  res.status(500).send('Server Error');
});

로그의 스택 트레이스가 가리키는 파일·줄을 따라가면 대부분 즉시 원인을 찾습니다. 핵심 원칙은 "500이 보이면 브라우저가 아니라 서버 로그를 본다"입니다. 브라우저 화면의 500 페이지에는 보안상 원인이 드러나지 않습니다. 로컬에서는 터미널 출력을, 배포 환경(Vercel·Heroku·AWS 등)에서는 해당 플랫폼의 로그 화면을 확인하세요. 또한 외부 입력(요청 본문, 쿼리 파라미터)을 검증 없이 그대로 쓰면 예기치 못한 값에서 500이 나므로, 입력 검증을 추가하면 같은 500이 400(잘못된 요청)으로 바뀌어 원인이 더 명확해집니다.

404 vs 500 비교

참고: 자주 보는 다른 상태 코드

예방

• API 라우트와 메서드를 문서(또는 OpenAPI)로 관리해 404를 줄이세요.
• 서버에 전역 에러 핸들러와 로깅을 반드시 두세요. 500의 진짜 원인은 로그에 있습니다.
• 외부 호출·DB 접근은 try/catch로 감싸 의미 있는 에러로 변환.
• SPA는 서버에 fallback 라우트를 설정해 새로고침 404를 방지.

자주 묻는 질문

Q1. 404가 났는데 경로는 맞는 것 같아요.

메서드(GET/POST)나 끝 슬래시, 대소문자, 베이스 경로(prefix)를 의심하세요. 네트워크 탭에서 실제 요청 URL과 서버 라우트 정의를 글자 그대로 대조하면 대부분 찾습니다.

Q2. 500인데 화면에 원인이 안 나와요.

정상입니다. 500은 일부러 내부 정보를 감춥니다. 원인은 서버 로그(또는 Vercel/Heroku 등 플랫폼 로그)의 스택 트레이스에 있으니 그곳을 보세요.

Q3. 404를 500으로 바꾸면 안 되나요?

안 됩니다. 상태 코드는 약속된 의미가 있습니다. 없는 리소스는 404, 서버 오류는 500으로 정확히 돌려줘야 클라이언트·모니터링·검색엔진이 올바르게 동작합니다.