genieus와 함께 알아보는 HTTP 상태코드

API 개발을 하다 보면 
항상 마주하는 상태 코드들이 있습니다.
특히 API에 문제가 생겼을 때 어디서 문제가 발생했는 지 
정확히 알기 위해서는 상태코드에 대한 이해가 필요합니다.
그래서 이번 포스팅 주제를 HTTP 상태코드로 정했습니다.

 

상태코드란?

클라이언트가 보낸 요청의 처리 상태를 응답에서 알려주는 기능

즉, 프론트엔드와 백엔드 간의 통신을 할 때 조금 더 명확한 정의를 위해 필요한 규칙으로 볼 수 있음.

HTTP 상태코드는 가이드라인이기 때문에 지키지 않는다고 문제가 발생하지는 않음.
하지만, 공용으로 통용되는 규칙이기 때문에 지켜서 개발한다면 어떤 개발자가 보더라도 명확하게 API를 이해할 수 있음.

---

1xx (Informational)

100번대 코드는 정보 전달 요청을 받았고, 작업을 진행 중이라는 의미
100번대 코드는 거의 사용하지 않아서 볼 일이 거의 없다고 생각하면 됨.
현재 해석된 100번대 코드는 아래와 같음.

• 100 Continue
• 101 Switching Protocols
• 102 Processing: 사용자가 수신요청을 하여 처리하고는 있지만 아직은 제대로 된 응답을 할 수 없는 상태임을 응답하는 코드
  WebDAV 전용
• 103 Early Hints: Link해더와 함께 사용되며 주로 서버가 응답을 준비하는 동안 사용자가 사전로딩(PreLoading)을 할수 있도록 하는 응답코드

2xx (Successful)

200번대 코드는 이 작업을 성공적으로 받았고, 이해했으며, 받아들여졌다는 의미

현재 해석된 200번대 코드는 아래와 같음.

• 200 OK : 성공적으로 처리했을 때 쓰임. 가장 일반적으로 볼 수 있는 HTTP 상태.
• 201 Created : 요청이 성공적으로 처리되어서 리소스가 만들어졌음을 의미. POST 상태에서 주로 사용됨.
• 202 Accepted : 요청이 받아들여졌지만 처리되지 않았음을 의미. 배치 처리에서 주로 사용됨.
• 203 Non-Authoritative Information : 응답받은 메타정보가 서버에 저장된 원본하고는 동일하지는 않지만 로컬이나 다른 복사본에서 수집되었음을 알리는 응답코드.
  이 경우에도 보통은 200 OK 응답코드가 203 Non-Authoritative Information 응답코드보다 우선적으로 응답.
• 204 No Content : 서버가 성공적으로 수행했지만, 응답 페이로드 본문에 보낼 데이터가 없음. 
  일반 사용자가 볼 일은 거의 드물며 처리 결과만 중요한 API 요청 등에서 주로 사용합니다. 즉, 결과가 아무 내용이 없어도 됨.
• 205 Reset Content : 서버가 요청을 성공적으로 처리했지만 콘텐츠를 표시하지 않는다.
  204 응답과 달리 이 응답은 요청자가 문서 보기를 재설정할 것을 요구한다 (예: 새 입력을 위한 양식 비우기).
• 206 Partial Content : 컨텐츠의 일부 부분만 제공한다.
  보통 클라이언트에서 시작 범위나 다운로드할 범위를 지정한 경우 자동으로 해당 부분만 제공할 때 사용하는 코드이다.
• 207 Multi-Status : 여러 소스에서 여러 응답인 상태에서 적절한 정보를 사용자한테 제공할수 있도록 하는 응답코드.
  WebDAV 전용.
• 208 Already Reported : DAV 바인딩 멤버는 이미 응답의 앞 부분에 열거되어 있으며 다시 포함되지 않는다고 응답하는 응답코드. WebDAV 전용.
• 226 IM Used : 서버가 사용자의 GET 요청에 대한 리소소의 의무는 다했고, 현재 인스턴스에서 적용된 하나 이상의 인스턴스 조작
  결과를 보낼 때 사용되는 코드. HTTP Delta Encoding 전용.

3xx (Redirection)

요청을 완료하기 위해 유저 에이전트의 추가 조치가 필요

현재 해석된 300번대 코드는 아래와 같음.

• 300 Multiple Choices(복수 응답) : 서버에서 여러 개의 응답이 있음을 알릴 때 사용할 의도로 만들어졌으나,
  정작 응답을 선택하는 방법은 표준화되지 않아 사용되지 않는다.
• 301 Moved Permanently(영구 이동) : 특정 리소스의 URI가 영구적으로 이동됨. client 웹 브라우저가 스스로 적절한 URL로
  URI를 바꿔서 새롭게 요청. 리다이렉트 시 요청 메서드가 GET으로 다 변하고, 본문이 제거될 수 있음. (MAY)
• 302 Found : 특정 리소스의 URI가 일시적으로 잠시 이동됨. 예를 들어, 주문 완료 후 주문 내역 화면으로 이동.
  PRG(Post/Redirect/Get) = 일시적인 리다이렉션, 301과 같이 요청 메서드가 GET으로 변함. 본문이 제거될 수 있음. (MAY)
• 303 See Other : 서버가 사용자의 GET 요청을 처리하여 다른 URL에서 요청된 정보를 가져올 수 있도록 응답하는 코드.
• 304 Not Modified : 캐시를 목적으로 사용. 클라이언트에게 리소스가 수정되지 않았음을 알려줌.  
  따라서, 클라이언트는 로컬 PC에 저장된 캐시를 재사용함. 304 응답은 응답에 메시지 바디로 포함하면 안됨.
• 305 Use Proxy(프록시 사용) : 프록시를 사용하지 않으면 접근할 수 없는 컨텐츠에 사용할 목적으로 만들어졌다. 이 응답 코드에는 요청자가 사용해야 하는 프록시 서버의 정보를 포함할 수 있다.
  다만 보안상 이유로 이 응답코드를 인식하는 브라우저는 없고 현재 사용 중지(Deprecated)된 비권장 응답코드.
• 306 (unused) : 초기 HTTP/1.1까지만 해도 Switch Proxy 요청으로 다음 요청시 지정한 프록시 서버를 사용하라는 응답 코드로
  초안이 각성되었으나 정작 사용이 되지 않았고 지금은 305 Use Proxy 응답이 사용 중지(Deprecated)되어 문서에서 삭제,
  예약코드로 있음. 
• 307 Temporary Redirect : 302와 동일하게 일시적인 컨텐츠 이동을 나타낼때 사용되나, HTTP 메서드의 변경을 허용하지 않음.
• 308 Permanent Redirect : 301와 동일하게 영구적인 컨텐츠 이동을 나타낼때 사용되나, HTTP 메소드의 변경을 허용하지 않음.

4xx (Client Error)

클라이언트의 요청에 잘못된 문법 등으로 서버가 요청 자체를 수행할 수 없음.

즉, 오류의 원인이 클라이언트에 있음. 

클라이언트가 이미 잘못된 요청, 데이터를 보내고 있기 때문에 똑같은 재시도가 실패함. 즉, 복구 불가능!!!

현재 해석된 400번대 코드는 아래와 같음.

• 400 Bad Request (잘못된 요청) : 클라이언트가 잘못된 요청을 해서 서버가 요청을 처리할 수 없음.
  예를 들어, 요청 파라미터가 잘못되거나, API 스펙이 맞지 않을 때 
• 401 Unauthorized (권한 없음) : 클라이언트가 해당 리소스에 대한 인증이 필요함.
  401 오류 발생 시 응답에 WWW-Authenticate 헤더와 함께 인증 방법을 설명해야함.
• 402 Payment Required (결제 필요) : 결제가 필요한 리소스에 결제없이 접근했을 경우 발생. HTTP/1.1에서 정의되었으나
  구현하지는 않고, 향후에 사용하기 위해 예약해둔 코드이다. 현재 딱히 표준조차도 존재하지 않음. 이런 상황에서는 보통 403을 사용.
• 403 Forbidden (거부됨) : 서버가 요청을 이해했지만 승인을 거부함. 인증 자격 증명은 있지만, 접근 권한이 불충분한 경우에 사용됨. 예를 들어, Admin 등급이 아닌 사용자가 로그인은 했지만, Admin 등급의 리소스에 접근하는 경우
• 404 Not Found (찾을 수 없음) : 요청 리소스가 서버에 없음.
  또는 클라이언트가 권한이 부족한 리소스에 접근할 때 해당 리소스를 숨기고 싶을 때 
• 405 Method Not Allowed (허용되지 않은 방법) : PUT이나 DELETE 등 서버에서 허용되지 않은 메소드로 요청시 사용하는 코드.
• 406 Not Acceptable (받아들일 수 없음) : 요청은 정상이나 서버에서 받아들일 수 없는 요청일시 사용하는 코드이다.
  보통 웹 방화벽에 걸리는 경우 이 코드가 반환됨. 
• 407 Proxy Authentication Required (프록시 인증 필요) : 프록시 인증이 필요할 경우 사용하는 코드이다.
• 408 Request Timeout (요청 시간 초과) : 요청 중 시간이 초과되었을때 사용하는 코드이다.
• 409 Conflict (충돌) : 사용자의 요청이 서버의 상태와 충돌하여 응답하는 코드이다.
• 401 Gone (사라짐) : 404와는 달리 찾는 리소스가 영원히 사라진 경우 사용하는 코드이다.
• 411 Length Required (길이 필요) : 서버에 요청시 Content-Length 값을 지정하지 않아 서버에서 응답을 거부할 때 쓰는 코드.
• 412 Precondition Failed (전제조건 실패) : 사용자가 서버로 조건부 요청(Conditional Requests)을 보낼 때 서버의 전제조건와 사용자의 전제조건이 맞지 않아 서버에서 응답 거부를 할때 쓰는 코드.
• 413 Payload Too Large (요청이 너무 긺) : 요청 본문이 너무 긴 경우 발생한다. 서버 소프트웨어로 NGINX를 사용하는 경우 기본 설정 그대로 사용하면 큰 첨부파일을 올릴 때 이 오류 코드가 발생하게 됨.
• 414 URI Too Long(URI가 너무 긺): URI가 너무 길 때 발생한다. 흔히 볼 수 있는 사례는 URL이 너무 긴 경우에 사용됨.
• 415 Unsupported Media Type(지원하지 않는 미디어 타입): 사용자가 요청한 미디어타입이 서버에서 지원하지 않는 타입이라서 응답을 거부할 때 쓰는 코드.
• 416 Requested Range Not Satisfiable(요청범위 부적합): 요청 헤더의 Range로 지정한 범위가 잘못되었을 때 발생.
• 417 Expectation Failed(예측 실패): 요청 헤더의 Expect값이 서버에서는 적절하지 못하다는 것을 응답할때 쓰는 코드이다.
• 418 I'm a teapot(찻주전자로 커피를 만들 수 없음.): 하이퍼텍스트 커피 포트 제어 프로토콜(HTCPCP)(RFC 2324)에서 사용되는 코드
• 421 Misdirected Request(잘못된 요청): 서버로 유도된 요청된 응답을 서버에서 생성할 수 없을때 응답하는 코드로 주로 TLS 인증서가 여러개 설치된 상태에서 꼬였을 경우 뜨는 오류.
• 422 Unprocessable Entity(처리할 수 없는 개체): 요청을 잘 받았으나 문법 오류로 인하여 응답할 수 없을때 사용되는 코드. WebDAV 전용.
• 423 Locked(잠김): 요청한 리소스가 잠겨있을때 뜨는 코드. WebDAV 전용.
• 424 Failed Dependency(실패한 종속성): 이전의 요청이 실패한 상태에서 지금의 요청도 실패한 경우 뜨는 코드.
  간단히 말해 요청 연속실패. WebDAV 전용.
• 425 Too Early(너무 일찍요청) : 서버가 재생될 수 있는 요청을 처리하는 데 위험을 감수하지 않는다는걸 알릴때 사용되는 코드이다.
• 426 Upgrade Required(업그레이드 필요): 클라이언트에서 보낸 요청의 프로토콜이 맞지 않아 현재 서버에서 처리할 수 없으나, 클라이언트가 프로토콜을 서버에서 지원하는 다른 프로토콜로 업그레이드 한다면 처리해 줄 수도 있는 상황에서 쓰는 응답 코드이다. 주로 서버의 응답에는 Upgrade 헤더와 필요한 프로토콜을 같이 응답한다. 보통 HTTP/1.1인 클라이언트가 HTTP/2만 지원하는 서버에서 요청할 때 뜸.
• 428 Precondition Required(전제 조건 필요): 서버로 요청을 할려면 요청이 조건부이어야만 할 때 뜨는 코드이다. 사용자가 PUT 요청을 하여 서버의 값이 수정되는 동안 다른 사용자가 서버의 상태를 수정하여 발생하는 충돌인 업데이트 상실를 막기 위해서 존재하는 코드.
• 429 Too Many Requests(너무 많은 요청): 일정 시간 동안 너무 많은 요청을 보냈을 때 이를 거부하기 위해 사용한다. 나무위키에서는 페이지 소스(/raw/문서명) 보기를 너무 자주 요청했을 때 임시 차단을 걸기 위해 사용되며 대다수 API에서 요청 제한을 나타내기 위해 사용한다.
• 431 Request Header Fields Too Large(요청 헤더 필드가 너무 큼): 요청한 헤더 값이 너무 커서 서버에서 처리를 하지 않는다는 걸 응답할 때 쓰는 코드이다. 보통 크기가 큰 쿠키와 캐시가 너무 쌓여져 있는 상태에서 서버에 요청할 때 뜨는 오류이다. 그리고 사용자 에이전트 변경프로그램으로 UA를 너무 길게 설정했을 때도 나온다. 캐시 및 쿠키를 정리하면 대부분 정상적으로 서버에서 응답한다.
• 451 Unavailable For Legal Reasons(법적인 이유로 차단됨): 국가 검열 등, 법적인 이유로 차단되었을 경우 사용할 수 있도록 정의된 코드이다. 서버는 Link 헤더로 차단된 근거가 되는 주소를 보낼 수 있다.

5xx (Server Error)

서버 오류. 서버 문제로 오류 발생. 서버에 문제가 있기 때문에 재시도 하면 성공할 수도 있음 (서버가 복구되는 경우)

현재 해석된 500번대 코드는 아래와 같음.

• 500 Internal Server Error (내부 서버 에러) : 서버에 오류가 발생해 작업을 수행할 수 없을 때 사용됨.
  보통 설정이나 퍼미션 문제. 아니면 HTTP 요청을 통해 호출한 문서가 실제 HTML 문서가 아니라 JSP, PHP, Servlet 등의
  프로그램일 경우 해당 프로그램이 동작하다 세미콜론을 빼먹는 등의 각종 에러로 비정상 종료를 하는 경우 이 응답코드를 보냄.
  그냥 쫌 애매하다 싶으면 500 에러를 내면 됨.
• 501 Not Implemented(요청한 기능 미지원): 서버가 요청을 수행하는데 필요한 기능을 지원하지 않는 경우 사용됨. 거의 볼 수 없음.
• 502 Bad Gateway (게이트웨이 불량) : 게이트웨이가 연결된 서버로부터 잘못된 응답을 받았을 때 사용된다.
• 503 Service Temporarily Unavailable (일시적으로 서비스를 이용할 수 없음) : 서비스를 일시적으로 사용할 수 없을 때 사용된다. 주로 웹서버 등이 과부하로 다운되었을 때 볼 수 있다. 거의 볼 수 없음.
• 504 Gateway Timeout (게이트웨이 시간초과) : 게이트웨이가 연결된 서버로부터 응답을 받을 수 없었을 때 사용된다.
• 505 HTTP Version Not Supported (지원되지 않는 HTTP 버전) : HTTP 버전을 서버가 처리할 수 없다. 브라우저는 서버가 처리 가능한 HTTP 버전을 자동으로 선택하므로, 웬만해서는 볼수 없는 오류이다.
• 506 Variant Also Negotiates : 서버 내부 구성(값)에 오류가 있어 반환되는 값에 컨텐츠 협상이 순환 참조로 이루어져 있다는걸 알려주는 코드.
•  
• 507 Insufficient Storage : 서버 내부 구성(값)에 오류가 있어 선택된 가변 리소스는 투명한 콘텐츠 협상에 참여하도록 구성되므로 협상 과정에서 적절한 끝점이 아님을 알려주는 코드. WebDAV 전용.
• 508 Loop Detected : 서버가 요청을 처리하는 동안 무한 루프를 발견하였을 때 뜨는 응답코드. WebDAV 전용.
• 510 Not Extended (확장되지 않았음) : 서버가 요청을 처리할때 요청에 대한 추가 확장이 필요한경우 뜨는 응답코드.
• 511 Network Authentication Required (네트워트 인증 필요) : 사용자가 네트워크 엑세스 권한이 필요한 경우 뜨는 응답코드. 보통 네트워크에 엑세스할 때 로그인이 필요한 경우 주로 뜬다.

---

상태코드는 처음와 말했듯이 약속입니다.
반드시 따를 필요는 없지만, 코딩을 하면서 팀원들과 의견을 통해 유연하게 사용하면 됩니다.
만약, 남의 코드를 보게 된다면 상태코드를 참고 하셔서 코드를 이해하시면 됩니다! 

참조 링크 및 자료
 - HTTP 상태코드 나무위키
 - 모든 개발자를 위한 HTTP 웹 기본 지식 from 김영한