HTTP 상태 코드
HTTP 상태 코드
HTTP 상태 코드는 서버가 클라이언트가 보낸 요청(Request)에 대해 어떤 결과가 발생했는지 나타내는 세 자리 정수입니다.
예를 들어, 서버가 정상적으로 요청을 처리했다면 2xx 범위의 상태 코드를 사용할 수 있으며, 요청에 문제가 있거나 처리가 불가능하다면 4xx 또는 5xx 범위를 사용할 수 있습니다.
이렇게 상태 코드를 통해 응답(Response)에 담긴 정보를 해석하고, 서버와 클라이언트 간 상호작용이 올바르게 이뤄지는지 점검할 수 있습니다.
아래는 상태 코드의 범주별 특징과 세부 코드입니다:
- 1xx(Informational): 정보 전송(요청을 계속 진행하라는 신호 등)
- 2xx(Success): 요청 성공
- 3xx(Redirection): 리소스 이동 또는 추가 조치 필요
- 4xx(Client Error): 클라이언트 잘못으로 요청을 처리할 수 없음
- 5xx(Server Error): 서버 잘못으로 요청을 처리할 수 없음
(그림 출처: 혼자 공부하는 컴퓨터 네트워크)
1xx: 정보(Informational) 상태 코드
1xx 범위(100~199)는 HTTP/1.1 이상에서 정의되며, 클라이언트에게 "현재 요청이 진행 중이니 계속해도 좋다"라는 식의 중간 응답을 줄 때 주로 사용합니다. 실무에서 빈번하게 사용하지는 않지만, 일부 프로토콜 업그레이드나 요청의 부분 처리를 알리기 위해 의미 있게 활용하기도 합니다.
- 100 (Continue)
서버가 요청 헤더를 잘 받았고, 본문 전송(예: 파일 업로드 등)을 계속 진행해도 된다는 뜻입니다. - 101 (Switching Protocols)
클라이언트가 다른 프로토콜(WebSocket 등)로 전환해 달라고 요구했을 때, 서버가 이를 승인하면 반환합니다. - 103 (Early Hints)
리소스(예: CSS, JS) 사전 로딩을 위해 브라우저에게 미리 지시하기도 합니다. 성능 최적화를 목적으로 가끔 활용합니다.
2xx: 성공(Success) 상태 코드
2xx 범위(200~299)는 클라이언트의 요청이 성공적으로 처리되었음을 의미합니다. HTTP 통신에서 가장 많이 사용되는 범위이기도 합니다.
(모두 그림 출처: 혼자 공부하는 컴퓨터 네트워크)
200 (OK)
가장 일반적인 성공 상태 코드입니다. GET 요청 시 해당 리소스를 정상적으로 전달할 수 있음을 나타냅니다. 예를 들어, http://example.com/images/a.png 에 GET 요청을 보냈을 때, 서버가 이미지를 정상적으로 찾고 반환하면 200(OK)을 함께 전송합니다.
201 (Created)
서버가 새로운 자원을 성공적으로 생성했을 때 사용합니다. 일반적으로 POST 요청의 응답에 많이 쓰이며, 생성된 자원의 경로(URI)는 Location 헤더에 담아서 알리는 것이 보통입니다.
202 (Accepted)
서버가 요청을 받았지만, 아직 처리가 완료되지 않았음을 나타냅니다. 대규모 파일 업로드나 배치 작업처럼 비동기 작업일 때 202(Accepted)를 응답합니다. 클라이언트는 실제 처리가 완료되었는지 확인하기 위해 추가적인 요청을 보낼 수 있습니다.
204 (No Content)
요청을 성공적으로 처리했으나, 응답 본문을 보낼 내용이 없을 때 사용합니다. 예를 들어, 데이터 수정이나 삭제 요청이 정상적으로 완료되었으나 별다른 응답 컨텐츠가 필요 없다면 204(No Content)를 응답할 수 있습니다.
3xx: 리다이렉션(Redirection) 상태 코드
3xx 범위(300~399)는 클라이언트가 요청한 자원이 다른 곳에 있거나, 추가 작업을 통해서만 요청을 완수할 수 있을 때 사용됩니다.
(그림 출처: 혼자 공부하는 컴퓨터 네트워크)
영구적(Permanent) 리다이렉션
- 301 (Moved Permanently)
- 308 (Permanent Redirect)
두 코드 모두 자원이 완전히 이동되었음을 의미합니다.
301(Moved Permanently)
다음 요청(재요청)에서 메서드가 GET으로 바뀔 수도 있음을 암시합니다. (RFC 9110 등 공식 문서에서도 "MAY change the request method"라고 표현)
308(Permanent Redirect)
301의 애매함을 없애고, 요청 메서드를 그대로 유지하도록 규정한 리다이렉션 코드입니다. 예를 들어, 처음에 POST 요청을 했다면 리다이렉트 후에도 POST 요청을 유지해야 합니다.
일시적(Temporary) 리다이렉션
- 302 (Found)
- 303 (See Other)
- 307 (Temporary Redirect)
클라이언트가 일시적으로 다른 곳을 참조해야 하는 경우 302(Found)를 사용해 왔으나, 여러 구현체가 서로 다르게 동작하여 혼선이 있었습니다. 이를 보완하기 위해 303(See Other)와 307(Temporary Redirect)이 도입되었습니다.
- 303(See Other)
재요청 시 메서드를 반드시 GET으로 전환해야 한다는 점을 명시합니다. - 307(Temporary Redirect)
재요청 시 메서드를 그대로 유지해야 함을 의미합니다.
예시로, 클라이언트가 POST 요청을 하고 307 응답을 받았다면, 재요청 시에도 POST를 그대로 사용해야 합니다.
반면, 303을 받은 경우에는 POST → GET으로 바뀝니다.
(모두 그림 출처: 혼자 공부하는 컴퓨터 네트워크)
304 (Not Modified)
캐시 처리와 관련된 상태 코드입니다. 클라이언트가 이미 리소스를 캐싱했으며, 그 리소스가 수정되지 않았으니 새롭게 다운로드할 필요가 없음을 의미합니다. 캐시-관련 헤더(예: If-Modified-Since, ETag)를 통해 클라이언트와 서버가 협상합니다. 이를 적절히 사용하면 트래픽과 서버 부하를 크게 줄일 수 있습니다.
4xx: 클라이언트 에러(Client Error) 상태 코드
4xx 범위(400~499)는 클라이언트에서 잘못된 요청을 보냈을 때 사용됩니다. (예: 쿼리 형식 오류, 인증 부족 등)
(그림 출처: 혼자 공부하는 컴퓨터 네트워크)
400 (Bad Request)
서버가 요청을 이해할 수 없을 때 반환합니다. 일반적으로 요청 메시지 구조가 이상하거나, 유효성 검사를 통과하지 못한 경우입니다.
401 (Unauthorized)
해당 요청을 처리하기 위해 인증이 필요한데, 클라이언트가 적절한 인증을 제공하지 않았거나 잘못된 인증 정보를 제공했을 때 발생합니다. 이 응답에는 반드시 WWW-Authenticate 헤더를 통해 인증 방식을 알리게 되어 있습니다.
403 (Forbidden)
클라이언트가 이미 인증을 했더라도, 권한(인가)이 부족하거나 접근이 허용되지 않는 자원에 접근하려고 할 때 발생합니다.
404 (Not Found)
서버 측에 존재하지 않거나, 비공개 처리되어 외부에서 볼 수 없는 자원에 대한 요청입니다.
405 (Method Not Allowed)
클라이언트가 요청한 HTTP 메서드(예: PUT, DELETE 등)가 서버에서 지원되지 않는 경우에 반환합니다. 예를 들어, 특정 엔드포인트가 GET과 POST만 허용하고 다른 메서드는 허용하지 않는다면, 그 메서드로 요청이 왔을 때 405를 응답합니다.
5xx: 서버 에러(Server Error) 상태 코드
5xx 범위(500~599)는 서버 내부 문제로 인해 정상적인 처리에 실패했을 때 사용됩니다. 이 범위의 응답이 자주 발생한다면 서버 로직이나 인프라 상태를 점검해야 합니다.
(그림 출처: 혼자 공부하는 컴퓨터 네트워크)
500 (Internal Server Error)
가장 대표적인 서버 에러 코드입니다. 예측하지 못한 예외나 버그로 요청을 처리할 수 없을 때 반환합니다. 정확한 원인은 서버 로그를 확인해야 합니다.
502 (Bad Gateway)
클라이언트와 서버 사이에 위치한 프록시, 게이트웨이 등 중간 서버가 잘못된 응답을 받았을 때 사용하는 코드입니다. 예를 들어, 프록시 서버가 백엔드 서버에 요청을 보내었는데, 백엔드 서버가 제대로 응답하지 않거나 잘못된 응답을 반환하면 502(Bad Gateway)로 표시합니다.
503 (Service Unavailable)
서버가 과부하이거나 유지 보수(점검) 중일 때, 일시적으로 서비스를 이용할 수 없음을 나타냅니다. 일정 시간이 지난 뒤 정상화되면 다시 2xx 혹은 다른 적절한 코드로 응답하게 됩니다.
참고 자료
- MDN Web Docs: HTTP 상태 코드
- RFC 9110 (HTTP Semantics)
- HTTPWG: HTTP Specifications
- 혼자 공부하는 컴퓨터 네트워크 (도서 자료)
HTTP 상태 코드는 웹 서비스에서 중요한 역할을 합니다. 상태 코드를 적절히 설계하고 해석하면, 서버-클라이언트 간 통신 흐름을 명확히 파악하고 문제 발생 시 신속히 대응할 수 있습니다.