CS

[CS] HTTP 상태 코드

tkxx_ls 2025. 3. 14. 23:43

HTTP 상태 코드(Http Status Code)

웹에서 클라이언트와 서버는 데이터를 주고받을 때 일정한 규칙을 따릅니다.

그 규칙 중 대표적인 것이 바로 HTTP(HyperText Transfer Protocol)입니다.

HTTP 프로토콜에서는 클라이언트가 보낸 요청이 서버에서 어떤 상태로 처리됐는지를 숫자로 알려주는 체계가 있는데,

이것을 HTTP 상태 코드(Status Code)라고 합니다.

 

 HTTP 상태 코드는 서버가 클라이언트의 요청을 처리한 결과를 나타내는 3자리 숫자입니다.

이 상태 코드를 통해 개발자는 요청의 성공 여부, 오류 원인, 리소스의 상태 등을 손쉽게 파악할 수 있습니다.

상태 코드는 크게 5가지 범위로 구분되는데, 각 범위마다 다음과 같은 의미를 가집니다.

  • 1xx (정보 제공) : 요청이 접수되어 처리 중임을 나타냅니다.
  • 2xx (성공) : 요청이 성공적으로 처리되었음을 나타냅니다.
  • 3xx (리다이렉션) : 요청 처리를 완료하려면 추가 작업이 필요함을 나타냅니다.
  • 4xx (클라이언트 오류) : 클라이언트의 요청에 문제가 있어 처리할 수 없음을 나타냅니다.
  • 5xx (서버 오류) : 서버에서 오류가 발생하여 요청 처리를 실패했음을 나타냅니다.

 

 

HTTP 상태 코드의 역사

HTTP 상태 코드는 웹의 창시자인 팀 버너스리(Tim Berners-Lee)가 1991년 HTTP 프로토콜을 처음 설계했을 당시부터 존재했습니다. 초기에는 몇 가지의 간단한 상태 코드만 존재했으나, 웹 기술이 발전하면서 더욱 체계화되었습니다. 특히 1996년 HTTP/1.0, 1997년 HTTP/1.1 표준이 발표되면서 현재 사용하는 대부분의 상태 코드가 정리되었고, 오늘날 HTTP/2와 HTTP/3에서도 이 상태 코드 체계가 계속 이어져 사용되고 있습니다.

 

 

HTTP 상태 코드를 사용하는 이유

HTTP 상태 코드는 클라이언트와 서버 사이의 의사소통을 명확하게 만들어줍니다.

개발자는 상태 코드를 통해 문제의 원인을 빠르게 찾고 디버깅할 수 있으며,

API 개발 시에는 일관된 상태 코드 사용으로 클라이언트 개발자의 개발 경험도 크게 향상할 수 있습니다.

결과적으로 상태 코드를 올바르게 이해하고 활용하는 것은 웹 개발자에게 꼭 필요한 역량이라고 할 수 있습니다.

 

 

HTTP 상태 코드의 종류와 의미

HTTP 상태 코드는 크게 5가지로 분류되며, 각 범주에 따라 의미와 용도가 다릅니다.

개발자로서 각 상태 코드의 의미와 대표적인 사례를 알아두면, API 설계나 디버깅 과정에서 많은 도움을 받을 수 있습니다.

 

정보 제공 (1xx)

1xx 상태 코드는 요청이 정상적으로 수신되었고, 처리가 진행 중임을 나타냅니다.

최종적인 응답이 아닌 중간 응답으로 사용됩니다.

  • 100 Continue
    클라이언트가 요청의 나머지 부분을 계속 보내도 괜찮음을 서버가 알려줍니다.
  • 101 Switching Protocols
    클라이언트가 요청한 프로토콜로 변경되었음을 나타냅니다. 주로 웹소켓(WebSocket)으로 전환할 때 사용됩니다.

 

성공 (2xx)

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

  • 200 OK
    요청이 성공적으로 완료되어 응답 본문에 요청한 데이터가 포함됩니다.
  • 201 Created
    요청이 성공적으로 처리되어 새로운 리소스가 생성되었음을 나타냅니다. 주로 POST 요청 이후 사용됩니다.
  • 204 No Content
    요청이 성공했지만 응답 본문에 보낼 데이터가 없을 때 사용합니다. 주로 DELETE 요청이나 PUT 요청 후 많이 사용됩니다.

 

리다이렉션 (3xx)

클라이언트가 요청한 리소스가 다른 곳으로 이동되었으며, 추가적인 처리가 필요함을 나타냅니다.

  • 301 Moved Permanently
    요청한 리소스가 영구적으로 새로운 URL로 이동되었음을 나타냅니다.
  • 302 Found
    요청한 리소스가 임시적으로 다른 위치에 존재함을 나타냅니다.
  • 304 Not Modified
    클라이언트가 이미 가진 캐시가 최신 상태이므로 새 데이터를 전송하지 않아도 됨을 알려줍니다.

 

클라이언트 오류 (4xx)

클라이언트가 잘못된 요청을 보내 서버가 처리할 수 없음을 나타냅니다. 주로 클라이언트가 문제를 해결해야 합니다.

  • 400 Bad Request
    요청이 잘못되었거나 형식이 올바르지 않아 처리할 수 없을 때 사용됩니다.
  • 401 Unauthorized
    요청한 리소스를 사용하려면 인증이 필요할 때 사용됩니다.
  • 403 Forbidden
    서버가 클라이언트의 요청을 이해했으나 권한 부족 등의 이유로 거부할 때 사용됩니다.
  • 404 Not Found
    클라이언트가 요청한 리소스가 서버에 존재하지 않을 때 사용됩니다.
  • 405 Method Not Allowed
    요청한 HTTP 메서드(GET, POST 등)가 허용되지 않을 때 사용됩니다.
  • 409 Conflict
    요청이 현재 서버 상태와 충돌하여 처리할 수 없을 때 사용됩니다.

 

서버 오류 (5xx)

서버에서 예상치 못한 문제가 발생하여 요청을 처리할 수 없음을 나타냅니다. 일반적으로 서버의 문제이므로 서버 측에서 해결해야 합니다.

  • 500 Internal Server Error
    서버 내부에서 오류가 발생하여 요청을 처리할 수 없을 때 사용됩니다.
  • 502 Bad Gateway
    게이트웨이나 프록시 역할을 하는 서버가 원본 서버에서 잘못된 응답을 받았을 때 사용됩니다.
  • 503 Service Unavailable
    서버가 과부하 상태이거나 유지보수 중이어서 일시적으로 요청을 처리할 수 없을 때 사용됩니다.
  • 504 Gateway Timeout
    게이트웨이나 프록시 서버가 원본 서버로부터 정해진 시간 안에 응답을 받지 못했을 때 사용됩니다.

 

HTTP 상태 코드 사용 시 주의할 점

상태 코드를 사용할 때는 아래와 같은 사항에 주의하면 좋습니다.

  • 명확하고 일관된 상태 코드를 사용해야 클라이언트 개발자가 쉽게 이해할 수 있습니다.
  • 상태 코드를 정확히 사용하는 것이 API의 품질과 유지보수성을 높이는 데 도움이 됩니다.
  • 에러 응답에는 상태 코드만 쓰는 것이 아닌 명확한 오류 메시지를 같이 보내는 것이 좋습니다.

 

참고 자료

 

HTTP 상태 코드 - HTTP | MDN

HTTP 응답 상태 코드는 특정 HTTP 요청이 성공적으로 완료되었는지 알려줍니다. 응답은 5개의 그룹으로 나누어집니다: 정보를 제공하는 응답, 성공적인 응답, 리다이렉트, 클라이언트 에러, 그리고

developer.mozilla.org