HTTP 상태코드
HTTP 상태코드 소개
이번 포스팅에서는 HTTP 상태코드에 대해 알아보겠습니다.
클라이언트(브라우저)가 서버로 요청(Request)을 보내면, 서버는 응답(Response)을 돌려주는데, 이 때 요청이 정상 처리되었는지, 혹은 문제가 있는지 상태코드(Status Code)를 통해 알려줍니다.
상태코드는 크게 다음과 같은 5가지 범위로 나눌 수 있습니다.
- 1XX (정보): 요청이 수신되어 처리 중(거의 사용하지 않음)
- 2XX (성공): 요청이 정상적으로 처리됨
- 3XX (리다이렉션): 요청을 완료하기 위해 추가적인 조치가 필요
- 4XX (클라이언트 오류): 클라이언트 요청에 문제가 있어 서버가 요청 수행 불가
- 5XX (서버 오류): 서버 내부 문제로 요청 처리 불가
미래에 새로운 상태코드가 추가되더라도, 앞의 첫 자리 숫자를 통해 큰 의미를 파악한 뒤 적절히 대응할 수 있습니다.
예를 들어 2XX 계열이면 성공, 3XX 계열이면 추가 조치(리다이렉션), 4XX면 클라이언트 오류, 5XX면 서버 오류라는 식으로 상위 카테고리에 따라 처리하면 됩니다.
1xx - 정보
- 1xx (Informational): 요청이 수신되어 처리 중임을 의미 거의 사용되지 않으므로 실무에서는 거의 볼 일이 없습니다.
2xx - 성공
2XX는 성공 상태코드로, 클라이언트 요청이 정상 처리되었음을 의미합니다.
가장 대표적인 상태코드는 다음과 같습니다.
- 200 OK: 요청을 성공적으로 처리함. 가장 일반적인 성공 코드
- 201 Created: 요청에 의해 서버에서 새로운 리소스가 생성됨. 주로
POST요청으로 신규 자원을 만들 때 사용하며, 응답 헤더에Location을 통해 생성된 리소스의 URI를 알려줄 수 있음 - 202 Accepted: 요청을 수신하였지만, 아직 처리를 완료하지 않음. 비동기 처리나 예약 처리 시에 사용 가능(실무에서 많이 사용되진 않음)
- 204 No Content: 요청은 성공적으로 수행되었지만, 응답 본문에 보낼 컨텐츠가 없음. 예를 들어 단순한 저장 요청 후 별다른 응답 본문 없이 성공만 알릴 때 사용
실무에서는 주로
200 OK,201 Created,204 No Content정도가 많이 사용됩니다.
모든 2XX 상태코드를 다 쓰는 경우는 드물며, 팀 내부 규칙에 따라 사용하는 범위를 정하는 것이 좋습니다.
3xx - 리다이렉션
3XX는 리다이렉션 상태코드로, 요청을 완료하기 위해 클라이언트(주로 브라우저)의 추가적인 액션이 필요함을 의미합니다.
대개 응답 헤더에 Location 필드를 포함하며, 클라이언트는 해당 Location으로 자동 요청을 재전송하여 최종 자원에 도달하게 됩니다.
대표적인 예는 다음과 같습니다.
영구 리다이렉션 (Permanent Redirection)
- 301 Moved Permanently 요청한 리소스의 URI가 영구적으로 이동했음을 의미합니다. 이전 URI를 더 이상 사용하지 않고,
Location에 제시한 새 URI를 사용해야 합니다. 브라우저, 검색 엔진 등은 이 정보를 기반으로 북마크나 인덱스를 갱신할 수 있습니다. - 308 Permanent Redirect 301과 기능은 비슷하나, 리다이렉트 시 메서드와 본문을 유지합니다. 다만 실무에서 308은 거의 쓰이지 않습니다.
일시적 리다이렉션 (Temporary Redirection)
- 302 Found: 일시적으로 다른 URI로 이동. 주로 브라우저 구현 상 POST 요청이 GET으로 변경될 수 있음
- 303 See Other: 클라이언트가 GET 요청으로 변경해서 새 URI로 요청하도록 명시적 지시
- 307 Temporary Redirect: 리다이렉션 시 요청 메서드와 본문을 변경하지 않고 그대로 유지
실무에서는 주로
302 Found를 많이 사용합니다.
비즈니스 로직에 따라 “POST 후 결과 페이지를 GET으로 보여주는” PRG(Post-Redirect-Get) 패턴에 자주 활용됩니다.
PRG 패턴이란?
서버에서POST요청이 여러번 요청되는 일을 막기 위해
POST요청이 오면 처리를 한 후, 결과페이지(GET)로Redirect하는 패턴이다.
특수 리다이렉션
- 304 Not Modified: 캐시를 사용하기 위한 리다이렉션. 클라이언트가 가진 캐시가 여전히 유효하므로 새로 자원을 내려주지 않고, 클라이언트는 캐시를 그대로 재사용할 수 있습니다. 응답 본문 없이 캐시 사용을 지시하여 네트워크 트래픽 절감 효과를 얻습니다.
4xx - 클라이언트 오류
4XX 상태코드는 클라이언트 요청에 오류가 있음을 의미합니다.
요청 문법 오류, 잘못된 파라미터, 권한 없음 등의 이유로 서버가 요청을 처리할 수 없습니다.
이 경우 같은 요청을 반복해도 성공할 수 없으며, 요청을 수정해야 합니다.
- 400 Bad Request: 잘못된 요청(문법 오류, 파라미터 오류)
- 401 Unauthorized: 인증(로그인) 필요.
WWW-Authenticate헤더로 인증 방법을 안내해야 함. (여기서 이름과 달리 ‘미인증’ 상태) - 403 Forbidden: 인증은 되었지만 접근 권한이 없음. 접근 권한 부족
- 404 Not Found: 요청한 리소스를 찾을 수 없음. 존재하지 않는 페이지나 자원
- 때로는 권한 부족 리소스를 숨기기 위해 404를 응답하기도 함
5xx - 서버 오류
5XX 상태코드는 서버 내부 문제로 요청을 처리할 수 없음을 의미합니다.
클라이언트 잘못이 아니므로, 서버 문제가 해결된 후 같은 요청을 재시도하면 성공할 가능성이 있습니다.
- 500 Internal Server Error: 서버 내부 오류 발생. 예외 처리 실패나 DB 장애 등
- 503 Service Unavailable: 서비스 이용 불가 (일시적 과부하나 서버 점검)
서버 개발 시 5xx 오류는 실제 서버 내부 문제가 생겼을 때만 내리는 것이 좋습니다.
비즈니스 로직 상 처리 불가능한 요청(예: 나이 미달 시 서비스 불가)은 400 계열로 내리는 것이 올바른 패턴입니다.
5xx 오류는 모니터링 툴 등에서 심각한 서버 상태를 나타내므로, 비즈니스 예외 상황에 사용해서는 안 됩니다.
정리
HTTP 상태코드는 크게 다음과 같이 이해할 수 있습니다.
- 1xx: 거의 사용하지 않음 (정보)
- 2xx: 요청 성공
- 3xx: 리다이렉션 필요 (추가 조치 요구)
- 4xx: 클라이언트 측 문제 (요청 수정 필요)
- 5xx: 서버 측 문제 (서버 복구 후 재시도 가능)
이러한 상태코드를 적절히 활용하면, 클라이언트-서버 간 명확한 커뮤니케이션과 효율적인 오류 처리 및 로직 분기를 할 수 있습니다.
다음 포스팅에서는 HTTP 헤더에 대해 깊이 있게 알아보겠습니다.
감사합니다.