[HTTP] 개발자가 꼭 알아야 할 HTTP 상태 응답 코드

개발자가 꼭 알아야 할 HTTP 상태 응답 코드 

 

HTTP 상태 코드란?

HTTP 상태 코드는 서버가 클라이언트의 요청을 처리한 결과를 알려주는 3자리 숫자입니다. 이 코드를 통해 요청이 성공했는지, 실패했다면 어떤 문제가 있는지를 빠르게 파악할 수 있습니다.

 

상태 코드의 분류

상태 코드는 첫 번째 숫자에 따라 5가지 종류로 구분됩니다:

 

1xx (정보 응답)

• 요청을 받았으며 작업을 계속한다는 의미
• 실제로는 자주 사용되지 않음

 

2xx (성공)

가장 자주 보게 되는 성공 상태 코드들입니다:

• 200 OK
  • 가장 일반적인 성공 응답
  • GET 요청이 성공적으로 처리됨
  • 실제 데이터가 응답 본문에 포함
• 201 Created
  • 새로운 리소스가 성공적으로 생성됨
  • POST 요청 후 새 리소스 생성 시 사용
  • 주로 회원가입, 게시글 작성 등에서 발생
• 204 No Content
  • 요청은 성공했지만 응답 본문이 없음
  • DELETE 요청 성공 시 주로 사용
  • 수정 작업 완료 후 새로운 데이터를 보내지 않을 때

 

3xx (리다이렉션)

클라이언트가 추가 동작을 취해야 할 때 사용됩니다:

• 301 Moved Permanently
  • 요청한 리소스가 새로운 URL로 영구 이동
  • 검색엔진이 기존 URL을 새 URL로 변경
• 302 Found
  • 일시적인 리다이렉션
  • 로그인 후 원래 페이지로 돌아갈 때 자주 사용
• 304 Not Modified
  • 캐시된 리소스가 여전히 유효함
  • 브라우저 캐시를 재사용해 네트워크 대역폭 절약

 

4xx (클라이언트 오류)

클라이언트 측의 문제를 나타냅니다:

• 400 Bad Request
  • 잘못된 문법으로 서버가 요청을 이해할 수 없음
  • 주로 잘못된 JSON 형식이나 유효하지 않은 파라미터
• 401 Unauthorized
  • 인증이 필요한 리소스에 인증 없이 접근
  • 로그인이 필요한 API에 토큰 없이 접근 시
• 403 Forbidden
  • 권한은 있으나 접근 권한이 없는 경우
  • 관리자 페이지에 일반 사용자가 접근 시
• 404 Not Found
  • 요청한 리소스가 서버에 없음
  • 잘못된 URL로 접근하거나 삭제된 리소스 요청 시
• 409 Conflict
  • 리소스의 현재 상태와 충돌
  • 이미 존재하는 이메일로 회원가입 시도 시

5xx (서버 오류)

서버 측의 문제를 나타냅니다:

• 500 Internal Server Error
  • 서버에서 처리 중 예상치 못한 오류 발생
  • 데이터베이스 연결 실패나 코드의 버그
• 502 Bad Gateway
  • 게이트웨이나 프록시 서버가 upstream 서버로부터 잘못된 응답
  • 로드밸런서나 프록시의 설정 문제
• 503 Service Unavailable
  • 서버가 일시적으로 요청을 처리할 수 없음
  • 서버 과부하나 유지보수로 인한 중단

 

상태 코드 사용 시 주의사항

1. 의미에 맞는 상태 코드 사용하기
   • 200으로 에러 처리하지 않기
   • 실제 에러 상황에서는 4xx, 5xx 사용
2. 일관성 있는 상태 코드 사용
   • 같은 상황에서는 같은 상태 코드 반환
   • API 문서화를 통한 상태 코드 명세
3. 적절한 에러 메시지 포함
   • 상태 코드만으로는 구체적인 문제를 알기 어려움
   • 응답 본문에 자세한 에러 정보 포함

 

---

401과 403 상태 코드의 차이점 완벽 정리

 

간단히 말하면:

• 401 Unauthorized: "누구신지 모르겠어요. 인증이 필요합니다."
• 403 Forbidden: "누구신지 알지만, 권한이 없습니다."

 

401 Unauthorized

• 인증(Authentication)과 관련된 상태 코드
• 클라이언트가 자신을 인증하지 않았거나 인증에 실패했을 때 발생
• 보통 로그인이 필요한 API에 인증 토큰 없이 접근할 때 발생
• WWW-Authenticate 헤더와 함께 어떤 인증 방식을 사용해야 하는지 알려줌

// JWT 토큰 검증 미들웨어
const authMiddleware = (req, res, next) => {
    const token = req.headers.authorization;
    
    if (!token) {
        return res.status(401).json({
            message: "인증 토큰이 필요합니다."
        });
    }
    
    // 토큰 검증 로직...
};

 

 

403 Forbidden

• 권한(Authorization)과 관련된 상태 코드
• 클라이언트의 신원은 확인됐지만 해당 리소스에 접근할 권한이 없을 때 발생
• 예를 들어 일반 사용자가 관리자 전용 API에 접근할 때 발생
• 추가적인 인증을 한다고 해도 접근이 허용되지 않음을 의미

// 권한 검증 미들웨어
const adminMiddleware = (req, res, next) => {
    const user = req.user; // 이미 인증된 사용자
    
    if (user.role !== 'ADMIN') {
        return res.status(403).json({
            message: "관리자만 접근 가능합니다."
        });
    }
    
    next();
};

 

 

실무에서 자주 마주치는 상황

1. 401 발생 상황
   • 로그인이 필요한 API 호출 시 토큰 누락
   • 만료된 토큰으로 API 호출
   • 잘못된 형식의 인증 정보 제공
2. 403 발생 상황
   • 일반 사용자가 관리자 페이지 접근
   • 다른 사용자의 개인정보 조회 시도
   • 결제하지 않은 사용자가 프리미엄 기능 접근