HTTP 상태 코드편집자 확인

HTTP/1.1 프로토콜에서 정의된 100 Continue는 임시 응답 상태 코드이다. 클라이언트가 서버로 보낸 요청 본문이 매우 크거나, 서버가 해당 요청을 처리할 의사가 있는지 사전에 확인이 필요한 경우에 사용된다. 클라이언트는 Expect: 100-continue 헤더를 요청에 포함시켜, 서버가 요청을 수락할 준비가 되었는지 먼저 물어볼 수 있다.

서버가 이 요청을 수락하고 처리할 의사가 있다면, 100 Continue 상태 코드로 응답한다. 이 응답을 받은 클라이언트는 비로소 나머지 요청 본문(예: 파일 업로드 데이터)을 서버로 전송한다. 만약 서버가 요청을 거절해야 한다면, 417 Expectation Failed나 4xx 계열의 다른 오류 코드를 즉시 반환하여 불필요한 데이터 전송을 중단시킨다.

이 메커니즘은 대용량 데이터를 전송하기 전에 사전 핸드셰이크를 수행함으로써 네트워크 자원을 절약하는 데 목적이 있다. 특히 파일 업로드나 스트리밍 데이터 전송과 같은 시나리오에서 유용하게 활용된다. 그러나 모든 서버와 클라이언트가 이 흐름을 완벽히 지원하는 것은 아니며, 일부 환경에서는 시간 초과 문제를 야기할 수도 있다.

101 Switching Protocols는 HTTP 상태 코드 중 하나로, 서버가 클라이언트의 요청을 이해하고 승인하며, 클라이언트가 요청한 프로토콜 전환을 수행할 준비가 되었음을 나타낸다. 이 응답 코드는 클라이언트가 Upgrade 요청 헤더를 포함하여 다른 프로토콜로 전환을 요청했을 때, 서버가 이를 수락하는 경우에 반환된다. 가장 일반적인 사용 사례는 HTTP/1.1 연결을 WebSocket이나 HTTP/2 같은 다른 프로토콜로 업그레이드하는 것이다.

서버가 101 응답을 보내면, 이는 연결이 사용 중인 기본 전송 프로토콜에서 요청된 새로운 프로토콜로 즉시 전환될 것임을 의미한다. 응답에는 반드시 클라이언트가 요청한 것과 동일한 Upgrade 헤더가 포함되어야 하며, 필요에 따라 다른 프로토콜별 헤더를 추가할 수 있다. 이 상태 코드 이후의 모든 데이터 교환은 새로 협상된 프로토콜의 규칙에 따라 이루어진다.

이 응답은 HTTP의 확장성과 다양한 프로토콜과의 상호 운용성을 보여주는 중요한 메커니즘이다. 단, 모든 서버가 모든 프로토콜 전환을 지원하는 것은 아니며, 서버는 Upgrade 헤더에 명시된 프로토콜 중 지원하지 않는 것이 있으면 101 응답을 보내지 않아야 한다.

102 Processing은 HTTP 상태 코드 중 하나로, 1xx - 정보 응답 범주에 속한다. 이 코드는 서버가 클라이언트의 요청을 수신했으며, 현재 요청을 처리 중임을 나타낸다. 최종 응답을 아직 보낼 수 없지만, 연결이 여전히 활성 상태임을 클라이언트에게 알리는 데 사용된다.

이 상태 코드는 주로 WebDAV와 같은 확장 프로토콜에서 사용된다. 서버가 요청을 처리하는 데 상당한 시간이 걸릴 수 있는 경우, 예를 들어 대용량 파일을 복사하거나 여러 작업을 포함하는 복잡한 요청을 실행할 때 중간 응답으로 전송될 수 있다. 이를 통해 클라이언트는 요청이 타임아웃되지 않고 진행 중임을 알 수 있다.

102 상태 코드는 최종 응답이 아니다. 서버는 요청 처리가 완료되면 200(OK)이나 201(Created)과 같은 다른 적절한 최종 상태 코드를 반드시 전송해야 한다. 이 코드는 RFC 2518(WebDAV)에서 처음 정의되었으며, 이후 RFC 4918에서 재확인되었다.

HTTP 요청이 성공적으로 처리되었음을 나타내는 기본 성공 응답 코드이다. 이 코드는 GET, HEAD, POST, PUT, DELETE 등 대부분의 메서드 요청이 정상적으로 완료되었을 때 사용된다. 응답의 의미는 요청된 메서드에 따라 달라지는데, 예를 들어 GET 요청에 대한 응답에는 요청한 리소스가 본문에 포함된다.

200 OK 응답의 본문 형식은 콘텐츠 협상을 통해 결정된다. 서버는 일반적으로 HTML, JSON, XML 등 클라이언트가 요청한 형식이나 협상된 형식으로 데이터를 반환한다. HEAD 요청에 대한 응답에서는 본문이 포함되지 않으며, 이 경우 헤더 필드만 전송된다.

다음은 200 OK 응답의 일반적인 구조 예시이다.

이 코드는 오류가 없이 요청이 수행되었음을 의미할 뿐, 반드시 리소스가 발견되었거나 변경되었음을 보장하지는 않는다. 예를 들어, 조건부 GET 요청에서 캐시된 리소스가 여전히 유효한 경우에도 200 OK와 함께 캐시된 리소스가 반환될 수 있다.

HTTP 요청이 성공적으로 처리되어 새로운 리소스가 생성되었음을 나타낸다. 이 응답은 일반적으로 POST 요청이나 일부 PUT 요청 이후에 전송된다.

응답에는 새로 생성된 리소스의 위치를 나타내는 Location 헤더가 포함되는 것이 일반적이다. 또한, 응답 본문에는 생성된 리소스의 상태를 설명하거나 리소스 자체에 대한 링크를 제공하는 것이 좋다. 예를 들어, 사용자 계정 생성 API에 POST 요청을 보냈을 때, 서버가 계정을 성공적으로 만들면 201 Created 상태 코드와 함께 새 사용자 프로필의 URI를 Location 헤더에 담아 반환한다.

201 Created는 단순히 요청이 성공했다는 것을 의미하는 200 OK와 구별된다. 200 OK는 요청을 처리했음을 알리지만, 반드시 새로운 리소스의 생성과 그 위치를 알려주지는 않는다. 따라서 새로운 항목이 서버에 추가되는 작업의 결과를 클라이언트에 명확히 전달하려면 201 Created를 사용하는 것이 적절하다.

HTTP 요청이 성공적으로 처리되었지만, 응답 본문에 반환할 콘텐츠가 없음을 나타낸다. 클라이언트는 HTTP 헤더를 포함한 응답은 수신하지만, 메시지 바디는 비어 있는 상태로 받는다.

이 상태 코드는 주로 PUT, POST, DELETE 요청 이후, 클라이언트의 현재 화면을 변경할 필요가 없을 때 사용된다. 예를 들어, 웹 API에서 자원을 업데이트하거나 삭제하는 작업이 성공했고, 별도의 성공 메시지나 새로 생성된 자원의 표현을 반환할 필요가 없을 때 적합하다.

204 응답은 캐시 가능하다. 그러나 ETag 헤더가 포함되지 않았다면, 클라이언트는 이후 동일한 요청에 대해 캐시된 응답을 재사용할 수 없다[1]. 응답은 반드시 본문을 포함하지 않아야 하며, 본문이 존재한다면 HTTP/1.1 프로토콜에 따라 서버가 본문을 전송하기 전에 Content-Length 헤더 필드를 0으로 설정해야 한다.

206 Partial Content 상태 코드는 서버가 클라이언트의 Range 헤더를 포함한 부분 요청을 성공적으로 처리했음을 나타낸다. 이 코드는 클라이언트가 리소스의 일부만 요청했을 때, 서버가 요청된 범위의 데이터를 정상적으로 반환했을 때 사용된다. 대용량 파일 다운로드나 미디어 스트리밍, 대용량 문서의 일부 읽기 등에서 효율적인 데이터 전송을 가능하게 한다.

클라이언트는 요청 시 Range 헤더를 사용하여 원하는 바이트 범위를 지정한다. 예를 들어, Range: bytes=0-999는 리소스의 처음 1000바이트를 요청하는 의미이다. 서버는 이에 성공적으로 응답할 경우, 206 Partial Content 상태 코드와 함께 Content-Range 헤더를 응답에 포함시켜 전송된 데이터의 실제 범위를 알려준다. 동시에 전체 리소스의 크기를 나타내는 Accept-Ranges: bytes 헤더도 함께 전송될 수 있다.

이 방식의 주요 이점은 네트워크 대역폭 절약과 전송 시간 단축이다. 다운로드가 중단된 대용량 파일을 다시 처음부터 받지 않고 중단된 지점부터 이어받는 재개 가능 다운로드 기능의 기반이 된다. 또한, 동영상 플레이어가 특정 구간을 점프하여 재생하거나, PDF 뷰어가 문서의 특정 페이지만 미리 로드하는 경우에도 활용된다.

단일 요청에 대해 여러 개의 독립적인 범위를 요청하는 것도 가능하다. 이 경우 서버는 multipart/byteranges 형식의 본문으로 응답하며, 각 파트마다 자신의 Content-Type과 Content-Range를 가진다. 그러나 모든 서버가 다중 범위 요청을 지원하는 것은 아니며, 서버의 구현에 따라 달라진다.

301 Moved Permanently는 HTTP 상태 코드 중 하나로, 요청한 리소스의 URI가 영구적으로 변경되었음을 나타낸다. 클라이언트는 향후 요청 시 응답 헤더의 Location 필드에 제공된 새로운 URI를 사용해야 한다. 이 코드는 일반적으로 URL 리다이렉션을 구현할 때 사용된다.

301 상태 코드의 응답은 캐시 가능하다. 검색 엔진과 같은 웹 크롤러는 이 응답을 받으면 리소스의 인덱싱 정보를 새 URL로 갱신한다. 이로 인해 검색 엔진 최적화 측면에서 기존 링크의 권한이 새로운 주소로 이전되는 효과가 있다.

이 코드는 웹사이트의 구조가 재구성되어 페이지의 주소가 바뀌었거나, 도메인 이름이 변경된 경우에 적합하다. 예를 들어, http://example.com/old-page가 https://example.com/new-page로 이동했을 때 301 응답을 반환하면, 사용자의 브라우저나 검색 엔진은 자동으로 새로운 주소를 사용하게 된다. 이는 사용자 경험을 유지하면서도 링크 쥐스를 방지하는 데 도움이 된다.

302 Found는 HTTP 상태 코드 중 하나로, 요청한 리소스가 일시적으로 다른 URI에 위치함을 나타낸다. 이 응답을 받은 클라이언트는 일반적으로 응답 헤더의 Location 필드에 제공된 새로운 주소로 요청을 자동으로 재전송한다. 원래의 상태 코드 명칭은 "Moved Temporarily"였으나, HTTP/1.1 명세에서 "Found"로 변경되었다.

이 코드는 요청된 리소스가 현재 다른 위치에서 제공되고 있지만, 나중에 원래의 주소로 돌아올 수 있음을 의미한다. 301 Moved Permanently와의 핵심적인 차이는 영구적인 이동이 아닌 일시적인 이동이라는 점이다. 따라서 검색 엔진은 302 Found 응답을 받았을 때, 새로운 주소를 인덱싱하더라도 원래 주소의 순위를 유지하는 것이 일반적이다.

초기 HTTP/1.0 명세에서는 이 코드의 동작이 명확히 정의되지 않아, 클라이언트가 POST 요청을 302 Found 응답 후에 GET 요청으로 변경하여 재전송하는 구현이 많았다. 이로 인해 예기치 않은 동작이 발생할 수 있어, HTTP/1.1에서는 307 Temporary Redirect와 303 See Other 코드를 추가하여 명확히 구분하였다. 302 Found는 여전히 GET 요청에 대한 리다이렉트로 널리 사용되지만, POST와 같은 안전하지 않은 메서드의 리다이렉트에는 307 Temporary Redirect를 사용하는 것이 권장된다.

HTTP 클라이언트가 조건부 요청을 보냈을 때, 서버가 해당 자원이 수정되지 않았음을 알리기 위해 사용하는 상태 코드이다. 이 응답을 받으면 클라이언트는 캐시에 저장된 자원의 사본을 계속 사용할 수 있다. 조건부 요청은 주로 If-Modified-Since나 If-None-Match와 같은 HTTP 헤더를 포함하여, 특정 날짜 이후로 변경되었거나 특정 ETag와 일치하지 않는 경우에만 새 자원을 전송하도록 요청하는 방식이다.

이 상태 코드는 네트워크 대역폭을 절약하고 서버 부하를 줄이는 데 핵심적인 역할을 한다. 응답 본문을 포함하지 않아야 하므로, 응답 헤더 필드만 전송된다. 일반적으로 Date, ETag, Cache-Control 등의 헤더가 함께 전달된다.

주로 정적 자원인 이미지, 스타일시트, 자바스크립트 파일 등을 제공할 때 활용된다. 웹 캐싱 메커니즘의 중요한 부분을 구성하며, 콘텐츠 전송 네트워크와 프록시 서버에서도 광범위하게 사용된다.

304 응답은 성공적인 상태 코드 범주인 2xx에 속하지 않지만, 리다이렉션을 의미하는 3xx 범주에 포함된다. 이는 클라이언트가 목표 자원에 접근하는 데 추가적인 조치(캐시된 사본으로 리다이렉트)가 필요하다는 의미로 해석된다.

307 Temporary Redirect는 클라이언트의 요청이 임시적으로 다른 URI로 리다이렉트되었음을 나타내는 HTTP 상태 코드이다. 이 응답을 받은 클라이언트는 원래의 요청 메서드와 본문을 변경하지 않고, 응답 헤더의 Location 필드에 명시된 새 주소로 동일한 요청을 반복해야 한다. 이는 302 Found와 유사하지만, 메서드 변경을 허용하지 않는다는 점에서 중요한 차이를 가진다.

307 상태 코드의 주요 목적은 요청의 메서드와 본문이 리다이렉트 과정에서 보존되도록 보장하는 것이다. 예를 들어, POST 요청으로 데이터를 전송하는 중에 이 코드를 받으면, 클라이언트는 동일한 데이터를 그대로 가지고 새 위치로 다시 POST 요청을 보내야 한다. 이는 302 Found나 303 See Other가 역사적으로 메서드를 GET으로 변경하도록 유도할 수 있었던 점과 대비된다.

이 코드는 주로 서버의 유지 보수나 일시적인 부하 분산과 같이 임시적인 상황에서 사용된다. 클라이언트는 향후의 요청도 반드시 원래의 URI로 보내야 하며, 캐시 가능성은 명시적으로 금지되지 않았지만, 임시적인 응답이므로 일반적으로 캐시되지 않는다.

HTTP/1.1 명세(RFC 7231)에서 도입된 307 상태 코드는 리다이렉트 시의 모호성을 줄이고, 멱등성이 보장되지 않는 요청(예: POST)의 안전한 재시도를 가능하게 하는 데 기여했다. 이후 등장한 308 Permanent Redirect는 이와 동일한 메서드 보존 규칙을 영구 리다이렉트에 적용한 쌍둥이 코드이다.

400 Bad Request는 HTTP 상태 코드 중 4xx 클라이언트 오류 범주에 속하는 코드이다. 이 상태 코드는 서버가 클라이언트의 요청을 이해할 수 없거나, 요청 문법이 잘못되었거나, 요청이 유효하지 않아 처리할 수 없음을 나타낸다. 오류의 원인이 명백히 클라이언트 측에 있기 때문에, 클라이언트는 요청을 수정하지 않고 동일한 요청을 반복해서 보내서는 안 된다.

일반적인 원인으로는 요청 URI의 문법 오류, 요청 메시지의 형식 오류, 크기가 너무 큰 요청 본문, 직렬화 오류가 있는 JSON 또는 XML 본문, 필수 HTTP 헤더의 누락 또는 형식 불일치 등이 있다. 예를 들어, 서버가 application/json 형식의 본문을 기대하는 API 엔드포인트에 클라이언트가 잘못된 JSON 구문을 보내거나, 필수 쿼리 파라미터를 생략한 경우 이 코드가 반환될 수 있다.

개발 및 디버깅 시, 서버는 응답 본문에 오류의 구체적인 원인을 설명하는 메시지를 포함시키는 것이 좋다. 그러나 이 정보는 최종 사용자보다는 API를 호출하는 클라이언트 개발자를 위한 것이어야 한다. 보안 상의 이유로 서버 내부 구조를 노출할 수 있는 지나치게 상세한 오류 메시지는 피해야 한다.

HTTP 상태 코드 401 Unauthorized는 클라이언트의 요청이 필요한 인증 자격 증명을 포함하지 않았거나, 제공된 자격 증명이 유효하지 않아 요청이 거부되었음을 나타낸다. 이 상태 코드는 RFC 7235에서 정의된다. "Unauthorized"라는 이름과 달리, 이 코드는 클라이언트의 신원이 확인되지 않았다는 의미이며, 실제로 인가(Authorization) 문제보다는 인증(Authentication)의 실패에 해당한다[2].

서버는 이 응답과 함께 WWW-Authenticate 헤더를 보내어, 요청된 리소스에 접근하기 위해 사용해야 할 인증 방식을 클라이언트에게 알려준다. 일반적인 인증 방식에는 Basic 인증, Digest 인증, Bearer 토큰(OAuth 2.0) 등이 있다. 클라이언트는 이 정보를 바탕으로 올바른 자격 증명(예: 사용자명과 비밀번호, API 키, JWT)을 포함하여 요청을 다시 시도해야 한다.

이 코드는 리소스의 존재 여부를 노출하지 않기 위해, 인증되지 않은 사용자에게 404 Not Found 대신 사용되는 경우도 있다. 그러나 인증은 성공했으나 해당 사용자에게 리소스 접근 권한이 없는 경우(인가 실패)에는 403 Forbidden 상태 코드를 반환하는 것이 적절하다.

403 Forbidden 상태 코드는 서버가 요청을 이해했지만, 인가되지 않아 요청을 거부했음을 나타낸다. 이는 401 Unauthorized와 구별되는데, 401은 인증 자체가 되지 않았음을 의미하는 반면, 403은 인증은 되었으나 접근 권한이 부족한 경우에 주로 발생한다. 서버는 거부 이유를 설명할 수 있지만, 보안상의 이유로 자세한 내용을 숨기는 경우가 많다.

이 오류가 발생하는 일반적인 시나리오는 다음과 같다.

* 사용자가 로그인했지만, 특정 디렉토리나 파일에 대한 읽기 권한이 없는 경우.

* 서버 구성(.htaccess 파일 등)에서 특정 IP 주소나 사용자 에이전트의 접근을 명시적으로 차단한 경우.

* 웹 애플리케이션의 접근 제어 로직에 의해 특정 역할(Role)이나 권한(Permission)을 가진 사용자만 접근할 수 있는 리소스에 권한 없는 사용자가 접근을 시도한 경우.

클라이언트는 동일한 자격 증명으로 재요청해도 성공할 수 없다. 문제를 해결하려면 서버 관리자에게 문의하거나, 애플리케이션의 경우 올바른 권한으로 로그인했는지 확인해야 한다. 서버 측에서는 보안을 유지하면서도 사용자 경험을 위해 보다 구체적인 오류 페이지(예: "이 콘텐츠를 볼 수 있는 권한이 없습니다.")를 제공하는 것이 좋다.

404 Not Found는 HTTP 상태 코드 중 가장 널리 알려진 클라이언트 오류 응답 코드이다. 이 코드는 서버가 요청받은 리소스를 찾을 수 없음을 의미한다. 서버는 해당 리소스가 존재하지 않거나, 접근 권한이 없어 존재 여부를 숨기고 싶을 때 이 상태를 반환할 수 있다. 일반적으로 클라이언트는 이 응답을 수신하면 사용자에게 해당 페이지를 찾을 수 없다는 메시지를 표시한다.

이 오류는 여러 상황에서 발생한다. 가장 흔한 원인은 사용자가 존재하지 않는 URL을 입력하거나, 페이지가 삭제 또는 이동되었을 때 잘못된 링크를 클릭하는 경우이다. 또한 서버의 파일 시스템 경로가 웹 서버 설정과 일치하지 않거나, .htaccess 파일 등의 설정 오류로 인해 발생하기도 한다. 개발 과정에서는 API의 엔드포인트 경로가 변경되었을 때 클라이언트가 이전 경로로 요청을 보내면 404 오류가 나타난다.

404 상태는 영구적인 오류를 의미하지는 않는다. 리소스가 나중에 복구되거나 다른 위치에서 사용 가능해질 수 있기 때문이다. 따라서 클라이언트(예: 웹 브라우저 또는 검색 엔진 크롤러)는 일반적으로 이 응답을 캐시하지 않는다. 웹사이트 관리자는 사용자 경험을 개선하기 위해 사용자 친화적인 커스텀 404 페이지를 제공하는 것이 일반적이다. 이러한 페이지는 사이트의 탐색 메뉴를 포함하거나 검색 기능을 제공하여 사용자가 원하는 콘텐츠를 찾을 수 있도록 도와준다.

429 Too Many Requests 상태 코드는 클라이언트가 짧은 시간 동안 너무 많은 요청을 보내 서버의 허용 한도를 초과했음을 나타낸다. 이는 일반적으로 속도 제한 또는 요청 쿼터 정책에 의해 트리거된다. 서버는 이 응답과 함께 Retry-After 헤더를 포함하여 클라이언트가 요청을 다시 시도하기 전에 얼마나 기다려야 하는지 알려줄 수 있다.

이 상태 코드는 HTTP/1.1 표준의 일부로 RFC 6585에서 정의되었다[3]. 주로 API 게이트웨이, 프록시 서버, 또는 웹 애플리케이션 자체에서 과도한 트래픽으로 인한 서비스 거부를 방지하고 서버 자원을 보호하기 위해 사용된다. 공격적인 크롤링, 브루트 포스 공격, 또는 단순한 클라이언트 버그로 인해 발생할 수 있다.

클라이언트는 이 응답을 받으면 요청 빈도를 줄여야 한다. Retry-After 헤더가 제공된다면, 그 시간(초 단위 또는 특정 날짜/시간) 이후에 요청을 재시도할 수 있다. 그렇지 않다면, 점진적으로 늘리는 지수 백오프 전략을 사용하는 것이 일반적이다. 서버 측에서는 이 코드를 통해 정상적인 사용자에게 서비스 이용 제한 사실을 명확히 알리면서도, 서비스 자체는 계속 가용 상태를 유지할 수 있다는 장점이 있다.

500 Internal Server Error는 HTTP 상태 코드 중 5xx - 서버 오류 범주에 속하는 일반적인 오류 응답이다. 이 상태 코드는 서버가 클라이언트의 요청을 처리하는 과정에서 예상치 못한 상황에 직면했으며, 보다 구체적인 오류 코드를 제공할 수 없음을 나타낸다. 서버 측에서 발생한 내부적인 문제로 인해 요청을 이행할 수 없음을 의미한다.

이 오류의 원인은 다양하다. 서버 측 애플리케이션 코드에 존재하는 버그, 데이터베이스 연결 실패, 서버 설정 오류, 의존성 라이브러리의 충돌, 또는 예외 처리가 되지 않은 런타임 오류 등이 일반적인 원인이다. 서버 로그 파일을 확인하면 구체적인 오류 메시지와 스택 트레이스 정보를 얻을 수 있어 문제 해결에 중요한 단서를 제공한다.

개발 및 운영 관점에서 이 상태 코드는 클라이언트에게 유용한 정보를 거의 제공하지 않는다. 따라서 프로덕션 환경에서는 가능한 한 구체적인 4xx - 클라이언트 오류 코드를 사용하거나, 500 오류가 발생할 경우 사용자에게 친숙한 에러 페이지를 보여주는 것이 좋다. 또한, 모니터링 시스템을 통해 500 오류 발생을 즉시 감지하고 조치할 수 있도록 하는 것이 중요하다.

502 Bad Gateway는 HTTP 상태 코드 중 5xx 서버 오류 범주에 속하는 코드이다. 이 코드는 서버가 게이트웨이나 프록시 서버 역할을 하면서, 요청을 처리하기 위해 접근한 상위 서버로부터 유효하지 않은 응답을 받았을 때 클라이언트에게 반환된다.

주로 서버 간 통신에서 문제가 발생했음을 나타낸다. 예를 들어, 웹 서버(예: Nginx, Apache)가 백엔드 애플리케이션 서버(예: PHP-FPM, Node.js, Tomcat)나 다른 업스트림 서버에 요청을 전달했을 때, 해당 서버가 완전히 다운되었거나, 응답을 완성하지 못하고 연결이 끊겼거나, 이해할 수 없는 형식의 응답을 보낸 경우에 발생한다. 이는 단일 서버의 내부 오류를 의미하는 500 Internal Server Error와 구별되는 지점이다.

이 오류는 일반적으로 서버 관리자나 백엔드 개발자가 해결해야 하는 문제이다. 해결을 위해 백엔드 서비스의 상태를 확인하고, 네트워크 연결을 점검하며, 서버 구성 파일의 설정을 검토하는 과정이 필요하다. 사용자(클라이언트) 측면에서는 페이지를 새로고침하거나 잠시 후 다시 시도하는 것이 일반적인 임시 조치이다.

503 Service Unavailable 상태 코드는 서버가 현재 요청을 처리할 수 없음을 나타낸다. 이는 일반적으로 서버가 과부하 상태이거나 점검 중이어서 일시적으로 사용할 수 없을 때 발생한다. 서버는 이 응답과 함께 Retry-After 헤더를 포함하여 클라이언트가 요청을 다시 시도하기까지 얼마나 기다려야 하는지 알려줄 수 있다.

이 상태는 서버 측의 일시적 문제로 인해 발생하므로, 클라이언트는 나중에 요청을 재시도하는 것이 적절하다. 서버가 유지 보수 중이거나, 트래픽 급증으로 인한 서버 과부하가 원인일 수 있다. 로드 밸런서 뒤의 특정 서버가 다운되었을 때도 이 코드가 반환될 수 있다.

다른 5xx 오류와의 차이점은 다음과 같다.

이 응답은 서비스가 일시적으로 중단되었지만, 나중에는 복구될 것임을 암시한다. 따라서 클라이언트는 지수 백오프 알고리즘 등을 사용하여 요청을 재시도하는 것이 바람직하다.

504 Gateway Timeout 상태 코드는 서버가 게이트웨이나 프록시 역할을 하면서, 요청을 처리하기 위해 접근한 업스트림 서버로부터 적시에 응답을 받지 못했을 때 반환된다. 이는 주로 두 서버 간의 통신 지연이나 업스트림 서버의 과부하로 인해 발생한다. 클라이언트에게 보내는 응답은 RFC 7231에 정의되어 있다.

이 오류는 클라이언트의 요청 자체에는 문제가 없지만, 서버 측의 통신 체인에서 문제가 발생했음을 의미한다. 일반적인 원인으로는 백엔드 애플리케이션 서버가 응답하지 않거나, 데이터베이스 쿼리나 외부 API 호출과 같은 작업이 설정된 타임아웃 시간을 초과하는 경우가 있다. 로드 밸런서 뒤의 서버가 다운되었을 때도 이 상태 코드가 나타날 수 있다.

문제 해결을 위해서는 먼저 업스트림 서버(예: 애플리케이션 서버)의 상태와 로그를 확인해야 한다. 또한 네트워크 연결 상태를 점검하고, 필요하다면 게이트웨이 서버의 타임아웃 설정 값을 증가시킬 수 있다. 모니터링 도구를 사용하여 서버의 응답 시간과 부하를 지속적으로 추적하는 것이 예방에 도움이 된다.

성공적인 요청을 처리한 후 서버는 적절한 2xx 상태 코드를 반환해야 한다. 가장 일반적인 성공 응답은 200 OK이다. 이 코드는 요청이 성공적으로 처리되었으며, 응답 본문에 요청된 리소스의 표현이 포함되어 있음을 나타낸다. 예를 들어, GET 요청으로 웹 페이지나 JSON 데이터를 조회하는 경우에 주로 사용된다.

새로운 리소스가 생성된 경우에는 201 Created를 사용하는 것이 적절하다. 이 코드는 요청이 성공했고, 그 결과로 새로운 리소스가 만들어졌음을 의미한다. 응답은 일반적으로 새로 생성된 리소스의 위치를 나타내는 Location 헤더와 함께 반환된다. POST 메서드를 사용하여 새로운 게시글을 작성하거나 파일을 업로드하는 API 엔드포인트에서 흔히 볼 수 있다.

요청은 성공했지만 응답 본문에 별도의 콘텐츠를 포함할 필요가 없는 경우에는 204 No Content를 사용한다. 이 상태 코드는 서버가 요청을 성공적으로 처리했지만, 클라이언트에 보낼 새로운 정보가 없음을 나타낸다. PUT 요청으로 기존 리소스를 완전히 대체하거나, DELETE 요청으로 리소스를 삭제한 후 성공을 알릴 때 자주 활용된다. 클라이언트는 이 응답을 받아도 현재 문서 뷰를 변경해서는 안 된다.

대용량 파일 다운로드나 스트리밍과 같이 Range 요청을 지원하는 경우, 206 Partial Content를 사용하여 요청된 바이트 범위의 데이터만 성공적으로 반환했음을 알린다. 적절한 성공 상태 코드를 선택하는 것은 API 설계의 명확성과 클라이언트의 정확한 동작을 보장하는 데 중요하다.

클라이언트 오류(4xx)와 서버 오류(5xx) 상태 코드는 각각 요청의 문제점이 어디에 있는지를 명확히 구분하여 반환해야 한다. 클라이언트의 잘못된 요청에는 4xx 코드를, 서버 측의 처리 실패에는 5xx 코드를 사용하는 것이 기본 원칙이다. 이 구분은 문제 해결의 책임 소재를 명확히 하고, 클라이언트와 서버 개발자가 각자의 영역에서 디버깅을 수행하는 데 도움을 준다.

일반적인 오류 처리 시나리오와 권장 상태 코드는 다음과 같다.

오류 응답 시에는 상태 코드만 반환하는 것보다, 문제를 설명하는 메시지를 응답 본문에 포함시키는 것이 좋다. 이 메시지는 개발자를 위한 디버깅 정보를 담을 수 있으나, 최종 사용자에게는 보안상 민감한 시스템 정보(예: 스택 트레이스, 데이터베이스 오류 메시지)가 노출되지 않도록 해야 한다. 또한, REST API 설계 시 일관된 오류 응답 형식(예: JSON 객체에 code, message, timestamp 필드 포함)을 정의하여 클라이언트의 오류 처리를 용이하게 한다.

리다이렉트는 클라이언트의 요청을 다른 URI로 전달하도록 지시할 때 사용된다. 주로 리소스의 위치가 영구적 또는 임시적으로 변경되었거나, 요청을 다른 처리 방식으로 전환해야 할 때 응답한다. 적절한 HTTP 상태 코드를 선택하는 것은 캐시 동작과 검색 엔진 최적화에 직접적인 영향을 미친다.

영구적인 리다이렉트는 301 Moved Permanently를 사용한다. 이는 해당 리소스의 URL이 완전히 새로운 주소로 옮겨졌으며, 검색 엔진과 사용자 에이전트가 향후 요청을 새 주소로 직접 보내야 함을 의미한다. 반면, 임시적인 이동이나 POST 요청의 메서드 변경 없이 일시적으로 다른 곳에서 리소스를 제공해야 할 때는 307 Temporary Redirect를 사용한다. 이전에 널리 사용되던 302 Found는 명세상 모호함이 있어, 임시 리다이렉트 시에는 307을 사용하는 것이 권장된다.

클라이언트가 조건부 요청을 보냈고 리소스가 수정되지 않아 캐시된 버전을 사용해도 될 때는 304 Not Modified를 반환한다. 이는 실제 본문 데이터를 전송하지 않으므로 대역폭을 절약한다. 다음 표는 주요 리다이렉트 시나리오와 권장 상태 코드를 정리한 것이다.

리다이렉트를 남용하면 사용자 경험을 저하시키고 페이지 로딩 시간을 불필요하게 증가시킬 수 있다. 특히 리다이렉트 체인을 생성하지 않도록 주의해야 한다. 또한, POST 요청에 대한 리다이렉트는 데이터 재전송 문제를 일으킬 수 있으므로, 307이나 308 상태 코드를 사용하여 명시적으로 메서드 변경을 금지하는 것이 안전하다.