HTTP 상태코드 적절하게 사용하기

서론

HTTP 요청을 보냈을 때, 웹 서비스는 적절한 상태코드와 함께 응답을 보내온다.

나는 여태 api 응답을 보낼 때 서버 문제면 500, 클라이언트 쪽 문제면 400으로만 보냈었는데, 최근 이와 관련해서 피드백을 받게 되었다.

이참에 상태코드에 대한 확실한 기준을 잡고 사용해보고 싶어 정리해보았다.

상태코드의 5가지 큰 분류

상태코드의 첫 번째 숫자에 따라 유형은 크게 5가지로 분류된다.

• 1xx : 정보. 요청을 받았으며 작업을 계속한다.
• 2xx : 성공. 요청을 성공적으로 받았고 인식했으며 수용하였다.
• 3xx : 리다이렉션. 요청 완료를 위해 추가 작업 조치가 필요하다.
• 4xx : 클라이언트 오류. 요청의 문법이 잘못되었거나 처리할 수 없는 요청이다.
• 5xx : 서버 오류. 서버가 유효한 요청에 대해 충족을 실패했다.

1xx : 조건부 응답

: 요청을 받았으며 작업을 계속한다.

• 100 : Continue. 지금까지 상태가 유효하며 클라이언트가 계속해서 요청을 하거나 이미 요청을 완료한 경우에는 무시해도 된다는 의미
• 101 : Switching Protocol. 요청자가 서버에 프로토콜 전환을 요청했고, 서버는 이를 승인하는 중이라는 의미
• 102 : Processing. 서버가 요청을 수신하였으며 이를 처리하고 있지만 아직 제대로 된 응답을 알려줄 수 없다.

2xx : 성공

클라이언트가 요청한 동작을 수신하여 성공적으로 처리했음을 의미.

• 200 : OK. 요청이 성공적으로 되었다. 서버가 요청한 페이지를 알맞게 제공했다는 의미.
• 201 : Created. 요청이 성공적으로 되었으며 서버가 새 리소스를 생성했다. POST 요청 또는 일부 PUT 요청 이후 따라온다.
• 202 : Accepted. 서버가 요청을 접수했지만 아직 처리하지 않았다. 다른 프로세스에서 처리 또는 서버가 요청을 수행하고 있거나 배치 동작을 하고 있는 경우에 사용한다.
• 203 : Non-Authoritative Information. 신뢰할 수 없는 정보. 서버가 요청을 성공적으로 처리했지만 컨텐츠를 제공하지 않는다는 의미.
• 204 : No Content. 컨텐츠 없음. 서버가 요청을 성공적으로 처리했지만 컨텐츠가 없기 떄문에 제공하지 않는다는 의미.
• 205 : Reset Content. 콘텐츠 재설정. 요청을 완수한 이후에 사용자 에이전트에게 이 요청을 보낸 문서 뷰를 초기화하라고 알려준다.
• 206 : Partial Content. 서버가 GET 요청의 일부만 성공적으로 처리했다.
• 207 : Multi-Status. 여러 리소스가 여러 상태 코드인 상황(다중 상태)이 적절한 경우에 해당되는 정보를 전달한다.
• 208 : Multi-Status. DAV에서 사용된다. propstatproperty와 status의 합성어) 응답 속성으로 동일 컬렉션으로 바인드된 복수의 내부 멤버를 반복적으로 열거하는 것을 피하기 위해 사용된다.
• 226 : IM Used. 서버가 GET 요청에 대한 리소스 의무를 다 했고 그 응답이 1개 이상의 인스턴스 조작이 현재 인스턴스에 적용이 되었음을 알려준다.

3xx : 리다이렉션 완료

클라이언트는 이 상태 코드를 받으면 요청을 마치기 위해 추가 동작을 취해야 한다.

• 300 : Multiple Choice. 서버가 요청에 대해서 하나 이상의 응답을 할 수 있다. 사용자 에이전트 또는 사용자는 그 중에 하나를 반드시 선택해야 한다.
• 301 : Moved permantly. 영구 이동. 요청한 리소스의 URI가 변경되었음을 의미한다. GET 또는 HEAD 요청에 대한 응답으로 이 응답 표시하면 요청자는 자동으로 새 위치가 전달된다.
• 302 : Found. 임시 이동. 요청한 리소스의 URI가 일시적으로 변경되었음을 의미한다. 새롭게 변경된 URI는 나중에 만들어질 수 있다. 클라이언트는 향후의 요청시 원래 위치를 계속 사용해야 한다.
• 303 : See Other. 기타 위치 보기. 클라이언트가 요청한 리소스를 다른 URI에서 GET 요청을 통해 얻어야 할 때 서버가 클라이언트로 직접 보내는 응답이다.
• 304 Not Modified. 수정되지 않음. 마지막 요청 이후 요청한 페이지는 수정되지 않았다. 서버가 이 응답을 표시하면 페이지의 콘텐츠를 표시하지 않는다.
• 305 Use Proxy. 프록시 사용. 클라이언트는 프록시를 사용하여 요청한 페이지만 액세스할 수 있다.
• 307 Temporary Redirect. 임시 리다이렉션. 현재 서버가 다른 위치의 페이지로 요청에 응답하고 있지만 클라이언트는 향후 요청 시 원래 위치를 계속 사용해야 한다.
• 308 Permanent Redirect. 영구 리다이렉션. 리소스가 이제 HTTP 응답 헤더의 Location 속성에 명시된 영구히 다른 URI에 위치하고 있음을 의미.

4xx : 요청 오류

클라이언트에 오류가 있음을 나타낸다.

• 400 : Bad Request. 잘못된 요청. 잘못된 문법으로 인해 서버가 요청을 이해할 수 없음을 의미한다.
• 401 : Unauthorized. 권한 없음. 이 요청은 인증이 필요함. 서버가 로그인이 필요한 페이지에 대해 이 요청을 제공할 수 있다. 클라이언트는 요청한 응답을 받기 위해 스스로 인증을 해야함.
• 402 : Payment Required. 결제 필요. 결제가 필요함. 사용되지 않고 있음.
• 403 : Forbidden. 금지됨. 클라이언트가 콘텐츠에 접근할 권리를 가지고 있지 않음. 예를 들면 사용자가 리소스에 접근 권한이 없음.
• 404 : Not Found. 찾을 수 없음. 서버가 요청한 페이지(리소스)를 찾을 수 없다.
• 405 : Method Not Allowed. 허용되지 않은 방법. 요청에 지정된 방법을 사용할 수 없다. POST 방식으로 요청 받는 서버에 GET 요청을 보내는 경우 또는 읽기 전용 리소스에 PUT 요청을 보내는 경우에 이 코드를 제공한다.
• 406 : Not Acceptable. 허용되지 않음. 요청한 페이지가 요청한 콘텐츠 특성으로 응답할 수 없다.
• 407 : Proxy Authentication Required. 프록시 인증 필요. 이 상태 코드는 401(권한 없음) 에러와 비슷하지만, 클라이언트가 프록시를 사용하여 인증해야 한다.
• 408 : Request Timeout. 요청시간 초과. 서버의 요청 대기가 시간을 초과하였다. 서버가 사용되지 않은 연결을 종료하고자 함을 의미한다.
• 409 : Conflict. 충돌. 서버가 요청을 수행하는 중에 출돌이 발생함을 표시한다 .서버는 응답할 때 충돌에 대한 정보를 포함해야 한다.
• 410 : Gone. 찾을 수 없음. 서버가 요청한 리소스가 영구적으로 삭제되었을 때 이 응답을 표시한다.
• 411 : Length Required. 길이 필요. 서버는 유효한 콘텐츠 길이 헤더 입력란 없이는 요청을 수락하지 않는다.
• 412 : Precondition Failed. 사전조건 실패. 서버가 요청자가 요청 시 부과한 사전조건을 만족하지 않는다.
• 413 : Payload Too Large. 요청 속성이 너무 큼. 요청이 너무 커서 서버가 처리할 수 없다.
• 414 : URI Too Long. 요청 URI가 너무 김. 요청 URI(일반적으로 URL)가 너무 길어 서버가 처리할 수 없다.
• 415 : Unsupported Mdeia Type. 지원되지 않는 미디어 유형. 요청된 데이터의 미디어가 지원하지 않는 형식으로 되어 있어서 서버가 요청을 거부한다.
• 416 : Requested Range Not Satisfiable. 처리할 수 없는 요청범위. 요청이 페이지에서 처리할 수 없는 범위에 해당되는 경우 서버는 이 상태 코드를 표시한다.
• 417 : Expectation Failed. 예상 실패. 서버는 Expect 요청 헤더 입력란의 요구사항을 만족할 수 없다
• 421 : Misdirected Request. 요청이 응답을 생성할 수 없는 서버로 지정되었다. 이것은 요청 URL에 포함 된 스키마와 권한의 조합에 대한 응답을 생성하도록 구성되지 않은 서버에서 전송할 수 있다.
• 422 : Unprocessable Entity. 처리할 수 없는 엔티티. 요청은 잘 형성되었지만 의미적 오류로 인해 추적할 수 없다.
• 423 : Locked. 잠김. 접근하고자 하는 리소스가 잠금되어있다.
• 424 : Failed Dependency. 실패된 의존성
• 425 : 정렬되지 않은 컬렉션, 인터넷 초안
• 426 : Upgrade Required. 업그레이드 필요. 클라이언트는 업그레이드 헤더 필드에 주어진 프로토콜로 요청을 보내야 한다.
• 428 : Precondition Required. 전제조건필요. 요청을 조건부로 요구.
• 429 : Too Many Requests. 너무 많은 요청. 사용자가 일정 시간 동안 너무 많은 요청을 보냈다.
• 431 : Request Header Fields Too Large. 요청 헤드 필드가 너무 큼. 헤더 필드가 너무 크기 때문에 서버가 요청을 처리하지 않는다. 요청 헤더 필드의 크기를 줄인 후에 요청을 다시 제출할 수 있다.

5xx : 서버 오류

서버가 유효한 요청을 명백하게 수행하지 못했음을 나타낸다.

• 500 : Internal Server Error. 내부 서버 오류. 서버에 오류가 발생하여 요청을 수행할 수 없다.
• 501 : Not Implemented. 구현되지 않음. 서버에 요청을 수행할 수 있는 기능이 없다. 예를 들어 서버가 요청 메소드를 인식하지 못할 때 이 코드를 표시한다.
• 502 : Bad Gateway. 불량 게이트웨이. 서버가 게이트웨이나 프록시 역할을 하고 있거나 또는 업스트림 서버에서 잘못된 응답을 받았다.
• 503 : Service Unavailable. 서비스를 사용할 수 없음. 서버가 요청을 처리할 준비가 되있지 않아서 발생한다. 일반적인 원인은 서버가 오버로드되었거나 유지관리를 위해 다운되었기 때문이다. 이는 대개 일시적인 상태이다.
• 504 : Gateway Timeout. 게이트웨이 시간초과. 서버가 게이트웨이나 프록시 역할을 하고 있거나 또는 업스트림 서버에서 제때 요청을 받지 못했을 때 발생한다.
• 505 : HTTP Version Not Supported. HTTP 버전이 지원되지 않음. 서버가 요청에 사용된 HTTP 프로토콜 버전을 지원하지 않는다.
• 506 : Variant Also Negotiates. 서버에 내부 구성 오류가 있다. 요청에 대한 투명한 내용 협상으로 인해 순환 참조가 발생한다.
• 507 : Insufficient Storage.용량 부족, WebDAV
• 508 : Loop Detected. 루프 감지됨(WebDAV) 서버가 요청을 처리하는 동안 무한 루프 감지.
• 509 : Apache bw/limited extension. 대역폭 제한 초과
• 510 : Not Extended. 확장되지 않음. 서버가 요청을 처리하기 위해서는 더 확장해야함.
• 511 : Network Authentication Required. 네트워크 인증 필요
• 598 : 네트워크 읽기 시간초과 오류, 알 수 없음
• 599 : 네트워크 연결 시간초과 오류, 알 수 없음

참고 자료

HTTP 상태 코드

HTTP 상태코드 정리

상태 코드, 뭘 줘야할까?