HTTP 상태 코드

HTTP 상태 코드?

HTTP 상태 코드는 클라이언트와 서버 간의 효과적인 커뮤니케이션을 위한 중요한 도구입니다.

HTTP 상태 코드는 클라이언트의 요청에 대한 서버의 응답 상태를 나타내는 3자리 숫자입니다. 이 코드는 아래와 같이 첫 번째 자리의 숫자에 따라 크게 5가지로 구분됩니다.

• 1xx (정보): 요청을 받고 프로세스 처리 중 (거의 사용하지 않음)
• 2xx (성공): 요청을 정상적으로 접수, 인식, 처리 
• 3xx (리다이렉션): 요청을 완료하려면 추가 행동 필요
• 4xx (클라이언트 오류): 요청 문법 오류 등으로 서버가 요청을 수행할 수 없음 (오류)
• 5xx (서버 오류): 서버가 정상적인 요청 처리 실패 (오류)

---

2xx - 성공 (Success)

2xx는 클라이언트의 요청이 성공적으로 처리되었음을 나타냅니다.

200 OK

• 가장 일반적인 성공 상태 코드
• GET 요청에 대한 정상적인 응답
• 요청한 데이터가 응답 본문(body)에 포함되어 있음

201 Created

• 리소스 생성 성공
• 주로 POST 요청에 대한 응답으로 사용
• Location 헤더에 생성된 리소스의 URI를 포함 

HTTP/1.1 201 Created
Location: /api/users/1   ← Location 헤더

202 Accepted

• 요청은 접수되었으나 처리가 완료되지 않은 상태
• 비동기 작업이나 배치 프로세스(일괄 처리)에서 사용 (ex: 월말 정산, 실시간 이메일 발송)
• 클라이언트에게 처리 상태를 확인할 수 있는 endpoint 제공 권장

204 No Content

• 요청은 성공했으나 응답 본문이 없는 경우
• 결과 내용이 없어도 성공 인식을 위해 사용
• ex: 저장 버튼을 눌러도 같은 화면을 유지하고 싶은 경우

---

3xx - 리다이렉션 (Redirection)

3xx는 요청 완료를 위해 유저 에이전트의 추가 작업이 필요한 경우를 나타냅니다.

리다이렉션은 웹 리소스의 위치가 변경되었을 때 클라이언트를 새로운 위치로 자동으로 안내하는 HTTP 응답입니다. 따라서  응답의 결과에 Location 헤더가 있다면 그 위치로 자동으로 이동하는 작업인 리다이렉트가 됩니다.

이런 리다이렉션은 도메인 변경, 로그인 후 페이지 이동 등에 사용됩니다. 예를 들어, 변경되기 전 도메인으로 요청이 들어올 경우 응답으로 새롭게 변경된 도메인으로 응답하면, 자동으로 리다이렉트가 되어 변경된 도메인으로 클라이언트가 다시 서버로 요청을 날리고 서버는 변경된 도메인으로 응답합니다.

 

리다이렉션의 종류는 아래와 같이 크게 3가지로 나눌 수 있습니다.

1. 영구 리다이렉션

리소스의 URI가 영구적으로 변경된 경우 사용합니다.

301 Moved Permanently

• 리소스가 새로운 URI로 영구 이동
• 검색 엔진이 새 URI로 업데이트
• GET으로 변할 수 있음 → 본문(body)이 제거될 수 있음

  HTTP/1.1 301 Moved Permanently
  Location: https://new-website.com/new-path    ← 새로운 URI로 영구 이동

308 Permanent Redirect

• 301과 유사하나 HTTP 메서드가 변경되지 않음
• POST 요청의 경우 본문(body) 데이터 유지

2. 일시 리다이렉션

리소스 URI의 일시적인 변경을 나타냅니다. 실무에서는 일시 리다이렉션을 가장 많이 사용합니다.

302 Found

• 리소스의 URI가 일시적으로 변경
• GET으로 변할 수 있음 → 본문(body)이 제거될 수 있음
• 원래 요청 방식(POST 유지 등)이 브라우저마다 다르게 동작할 수 있음

303 See Other

• 리소스가 다른 URL에서 확인 가능하며
• 302와 비슷하지만 303은 항상 GET 요청으로 리디렉션해야 함

307 Temporary Redirect

• 302와 유사하나 HTTP 메서드가 변경되지 않음
• POST 요청의 경우 본문(body) 데이터 유지

PRG(Post/Redirect/Get) 패턴

• POST 요청 후 리다이렉션을 통해 GET으로 전환
• 새로고침 시 중복 요청 방지
  • ex: 결제 페이지를 새로고침할 시 똑같은 주문이 반복에서 들어갈 수 있음 → GET으로 전환하여 주문 확인 페이지로 이동
• 주의: 서버에서도 당연히 위와 같이 중복적인 요청이 들어오는 경우를 대비해야함 

POST /order HTTP/1.1  	← 주문 요청
HTTP/1.1 302 Found    	← 리다이렉션
Location: /order/12345  ← 주문 확인 페이지로 이동

 

3. 특수 리다이렉션

304 Not Modified

• 캐시된 리소스가 최신 상태
• 클라이언트는 로컬 캐시를 사용
• 응답에 본문(body)을 포함하지 않아 대역폭 절약

---

4xx - 클라이언트 오류 (Client Error)

4xx는 클라이언트의 잘못된 요청을 나타냅니다. 따라서 클라이언트가 같은 요청을 계속 보내도 계속 실패합니다.

400 Bad Request

• 잘못된 요청 구문 등의 오류
• 요청 구문이나 메시지 등을 클라이언트에서 검토하고 다시 보내야 함

401 Unauthorized

• 리소스에 접근하기 위해 인증 필요
• 클라이언트가 인증(로그인과 같은 본인 확인)이 되지 않음 → 인증 필요
• 응답으로  WWW-Authenticate 헤더와 함께 인증 방법 설명

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="My App"   ← WWW-Authenticate 헤더

403 Forbidden

• 서버가 요청은 이해했지만 승인 거부
• 클라이언트의 권한 부족 ← 인증(로그인과 같은 본인 확인)은 되었으나 권한은 없음

404 Not Found

• 요청 리소스를 서버에서 찾을 수 없음
  • ex: 나의 블로그 게시글은 8개만 있지만 엔드포인트로 /100을 주면 해당 오류가 나타남(서버에는 100번째 게시글이 없음) 지금 한 번 해보세요..! 개발자 도구에 Console에서 확인할 수 있습니다!
• 클라이언트 권한 부족으로 리소스 존재를 감추기 위해서도 사용

---

5xx - 서버 오류 (Server Error)

5xx은 서버 측 문제를 나타냅니다. 따라서 이 오류는 서버에서 문제를 해결하면 같은 요청이 들어와도 성공할 수 있습니다. 

5xx 에러는 최소화해야 합니다. 서버 문제를 의미하므로 철저한 예외 처리가 필요합니다. 따라서 비즈니스 로직상의 예는 4xx이나 2xx로 처리합니다. (ex: 잔액 부족 → 400)

500 Internal Server Error

• 서버 내부 오류
• 애매한 상황에서는 500 에러

502 Bad Gateway

• 게이트웨이 오류
• 게이트웨이: 네트워크에서 서로 다른 네트워크 간에 통신을 가능하게 하는 컴퓨터나 소프트웨어

503 Service Unavailable

• 서비스 일시 중단 (예정된 작업 등)
• 서버의 일시적 과부하

---

[참고자료]

https://docs.whatap.io/url/url-http-status

강의: 모든 개발자를 위한 HTTP 웹 기본 지식