HTTP 상태 코드 조회이란?
HTTP 상태 코드는 웹 서버가 모든 응답과 함께 반환하는 세 자리 숫자로, 요청이 성공했는지, 리디렉션이 필요한지, 실패했는지, 그리고 그 이유를 클라이언트(브라우저, 앱, API 소비자)에게 알려줍니다. IETF에 의해 표준화되어 모든 웹 서버, 브라우저, 프로그래밍 언어에서 동일하게 사용되므로, 소프트웨어 개발에서 가장 보편적인 디버깅 참조 중 하나입니다.
이 조회 도구는 정보(1xx), 성공(2xx), 리디렉션(3xx), 클라이언트 오류(4xx), 서버 오류(5xx)의 다섯 가지 범주에서 가장 자주 접하는 코드를 모두 다루며, 각 코드가 실제로 어떤 의미인지 형식적인 RFC 정의뿐만 아니라 이해하기 쉬운 설명을 제공합니다.
이 계산기를 사용해야 할 때
- 요청이 실패하고 상태 코드가 실제로 무엇을 의미하는지 이해해야 하는 API 통합을 디버깅
- 특정 오류 조건에 대해 자신의 API에서 어떤 HTTP 상태 코드를 반환할지 결정
- 웹 개발 강의나 Bootcamp에서 HTTP 기초를 가르치거나 배우기
- 서로 다른 4xx, 5xx 상황을 구분해야 하는 오류 처리 미들웨어 작성
- 301이 반환되었는지 302가 반환되었는지 확인하여 리디렉션이 왜 작동하지 않는지 조사
- 브라우저가 네트워크 오류를 표시하지만 서버가 200을 반환한 CORS 문제 해결
단계:
- 검색창에 상태 코드(예: 404) 또는 키워드(예: "forbidden")를 입력하세요.
- 특정 범위를 살펴보려면 1xx-5xx 버튼으로 범주별 필터링을 사용하세요.
- 각 코드가 무엇을 의미하고 언제 주로 반환되는지 쉬운 말 설명을 읽으세요.
- API 응답을 디버깅하거나 오류 처리 로직을 만들 때 빠른 참고 자료로 활용하세요.
공식
1xx: 정보성 — 요청을 수신했으며 처리를 계속함
2xx: 성공 — 요청이 성공적으로 수신되고 수락됨
3xx: 리디렉션 — 요청을 완료하려면 추가 작업이 필요함
4xx: 클라이언트 오류 — 요청의 문법이 잘못되었거나 처리할 수 없음
5xx: 서버 오류 — 서버가 유효한 요청을 처리하지 못함
사용 사례
- 연동 중인 API가 반환한 낯선 상태 코드를 빠르게 이해
- 특정 오류 조건에 대해 자신의 API에서 어떤 상태 코드를 반환할지 결정
- 특정 코드가 실제로 무엇을 의미하는지 확인해 요청 실패 원인 디버깅
- 웹 개발 강의에서 HTTP 기초를 가르치거나 배우기
- 서로 다른 4xx, 5xx 상황을 구분하는 정확한 오류 처리 로직 작성
주요 이점
- 자주 쓰이는 모든 상태 코드를 하나의 검색 가능한 참고 자료로 제공
- 형식적인 RFC 문구가 아닌 쉬운 말 설명
- 범주(1xx부터 5xx까지)로 즉시 필터링
- 무료이며 빠르고 가입이 필요 없음
전문가 팁
- 5xx 코드는 엄격하게 서버 측 실패에만 사용하고, 클라이언트 입력 오류를 나타내는 데는 절대 사용하지 마세요
- 속도 제한 시 Retry-After 헤더와 함께 429를 사용해 잘 동작하는 클라이언트가 언제 재시도할지 알 수 있게 하세요
- 리소스가 실제로 존재하지 않을 때는 일반적인 오류 페이지 대신 404를 사용하는 것이 사용자와 검색 엔진 모두에 좋습니다
- API를 설계할 때는 모든 것을 일반적인 400으로 처리하기보다 구체적인 4xx 코드(422, 409, 400)를 선택하세요
피해야 할 일반적인 실수
- 실제로 실패한 요청에 200 OK를 반환해 모니터링 도구로부터 오류를 숨김
- 401(인증되지 않음)과 403(인증되었으나 권한 없음)을 혼동
- 영구적이어야 할 리디렉션(301)에 302를 사용해 SEO에 손해를 끼침
- 클라이언트 측 오류 처리에서 모든 4xx, 5xx 오류를 특정 코드로 분기하지 않고 동일하게 취급
주요 용어 설명
- 상태 라인(Status line): 상태 코드와 짧은 사유 문구를 포함하는 HTTP 응답의 첫 줄
- 멱등성(Idempotent): 동일한 요청을 반복해도 한 번 실행한 것과 같은 효과를 내는 특정 HTTP 메서드의 속성
- 리디렉션 체인(Redirect chain): 브라우저가 최종 리소스에 도달하기 전에 따라가는 여러 리디렉션의 연속
- 속도 제한(Rate limiting): 특정 시간 창 내에 클라이언트가 보낼 수 있는 요청 수를 제한하며, 흔히 429로 신호를 보냄
관련 개념
예시
"429"를 검색하면 "Too Many Requests"가 반환됩니다. 이는 API에서 요청 제한을 초과했을 때 반환되는 코드로, 속도를 낮추고 일정 시간 후 재시도하라는 의미입니다.
결과 해석 방법
HTTP 상태 코드는 첫 번째 숫자에 따라 다섯 가지 클래스로 그룹화됩니다. 1xx는 정보 제공용으로 애플리케이션 코드에서 거의 볼 수 없습니다. 2xx는 성공을 확인합니다 — 200 OK가 가장 일반적이지만 201 Created와 204 No Content도 REST API에서 자주 사용됩니다. 3xx는 리디렉션을 처리하며 301(영구)과 302(임시)가 가장 중요합니다.
4xx 오류는 클라이언트 요청에 문제가 있음을 나타냅니다. 가장 흔한 것은 400 Bad Request(잘못된 구문), 401 Unauthorized(인증되지 않음), 403 Forbidden(권한 없음), 404 Not Found(리소스 없음), 429 Too Many Requests(속도 제한 초과)입니다. 특정 4xx 코드를 올바르게 사용하면 모든 것에 일반적인 400을 반환하는 것보다 훨씬 디버깅하기 쉬운 API가 됩니다.
5xx 오류는 서버가 실패했음을 의미합니다. 500은 포괄적인 내부 오류, 502 Bad Gateway는 업스트림 서버 문제를 나타내며, 503 Service Unavailable은 보통 서버 과부하 또는 유지보수 중임을 뜻합니다. 5xx 오류를 디버깅할 때는 클라이언트 응답 대신 서버 로그를 확인하세요. 상태 코드만으로는 근본 원인을 거의 알 수 없기 때문입니다.