HTTP 상태 코드

HTTP 상태 코드는 서버가 요청 결과를 설명하기 위해 응답에 포함하는 세 자리 숫자입니다. 200은 요청 성공, 404는 페이지를 찾을 수 없음, 500은 서버 오류를 의미합니다. 첫 번째 자리는 코드를 다섯 가지 클래스 중 하나로 분류합니다. 2xx는 항상 성공, 5xx는 항상 서버 오류를 나타내므로, 클래스만 알아도 디버깅 시작 지점을 즉시 파악할 수 있습니다. 클라이언트 측인지 서버 측인지를 먼저 결정하는 것이 핵심입니다.

첫 번째 자리가 클래스를 정의합니다. 1xx 정보(요청이 수신되어 처리 중, 예: 100 Continue), 2xx 성공(처리 완료, 예: 200 OK), 3xx 리디렉션(다른 위치로 이동 필요, 예: 301 Moved Permanently), 4xx 클라이언트 오류(요청이 잘못됨, 예: 404 Not Found), 5xx 서버 오류(서버 실패, 예: 500 Internal Server Error)입니다. 위 도구에서 클래스별로 필터링하면 각 코드의 설명과 함께 해당 그룹만 볼 수 있습니다.

일상적으로 마주치는 주요 코드는 200 OK, 201 Created, 204 No Content, 301과 302 리디렉션, 304 Not Modified, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests, 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable입니다. 위 도구에서 '자주 쓰이는 코드만 보기'를 켜면 전체 목록을 이 간략한 세트로 필터링하여 각각의 원인과 해결 방법을 확인할 수 있습니다.

200 OK는 표준 성공 응답으로, GET 요청에서는 응답 본문에 리소스를 반환하고 POST 요청에서는 작업 결과를 반환합니다. 201 Created는 POST 또는 PUT이 성공하여 새 리소스가 생성되었음을 의미합니다. 서버는 보통 Location 헤더에 새 리소스의 주소를 넣습니다(예: Location: /users/42). API를 개발하면서 리소스를 생성하는 경우라면 200이 아닌 201과 Location 헤더를 반환하여 클라이언트가 새 객체를 어디서 찾을 수 있는지 알 수 있도록 해야 합니다.

404는 서버가 해당 URL에서 아무것도 찾지 못했다는 의미입니다. 해당 페이지가 존재하지 않거나, 이동되었거나, 링크가 깨진 것입니다. URL 오타나 대소문자 오류를 확인하고, 이전 주소에서 새 주소로 301 리디렉션을 추가하고, 서버의 라우팅이나 재작성 규칙을 검증하고, 유용한 커스텀 404 페이지를 제공하세요. 410 Gone과 달리 404는 리소스가 영구적으로 사라졌다는 보장이 없으므로 검색 엔진은 계속 크롤링합니다. MDN Web Docs가 스펙을 잘 설명하지만, 이 도구는 각 코드와 함께 일반적인 원인과 해결 방법을 바로 보여 줍니다.

301 Moved Permanently는 리소스가 영구적으로 새 위치로 이동했음을 의미하므로, 검색 엔진은 순위 신호를 새 URL로 이전하고 색인을 업데이트합니다. URL을 영구적으로 변경할 때 사용하세요. 302 Found는 임시 이동으로, 원래 URL이 표준으로 유지되고 순위도 그대로 남습니다. A/B 테스트나 점검 페이지 같은 단기 이동에 사용하세요. GET이 아닌 요청(POST 등)에는 308(영구) 또는 307(임시)을 대신 사용하세요. 이 코드들은 HTTP 메서드를 그대로 유지하여 브라우저가 POST를 GET으로 다운그레이드하는 것을 방지합니다.

403 Forbidden은 서버가 요청을 이해했지만 승인을 거부한다는 의미입니다. 401과 달리 인증 정보를 보내도 도움이 되지 않습니다. 일반적인 원인으로는 계정의 권한이나 스코프 부족, 서버의 잘못된 파일 권한(예: 파일이 644 대신 600으로 설정), IP 차단이나 WAF 규칙, 또는 인덱스 파일 없이 디렉터리 목록이 비활성화된 경우가 있습니다. 계정 역할, 파일 권한, 허용 목록을 확인하세요. 일부 서버는 리소스 존재 여부를 숨기기 위해 의도적으로 404 대신 403을 반환하기도 합니다.

모두 5xx 서버 오류이지만 의미가 다릅니다. 500 Internal Server Error는 일반적인 '뭔가 잘못됨' 응답으로, 보통 앱의 처리되지 않은 예외나 버그입니다. 502 Bad Gateway는 프록시가 업스트림 앱 서버로부터 잘못된 응답을 받은 경우(주로 크래시)입니다. 503 Service Unavailable은 서버가 일시적으로 다운되었거나 과부하 상태임을 의미하며, Retry-After 헤더가 포함되어야 합니다. 504 Gateway Timeout은 업스트림에 연결은 되었으나 제때 응답하지 않은 경우입니다. 실제로 이를 구분하려면 서버 로그부터 확인하세요.

429는 일정 시간 동안 요청을 너무 많이 보내 속도 제한에 걸렸다는 의미입니다. 서버는 얼마나 기다려야 하는지 알려 주는 Retry-After 헤더를 포함해야 합니다. 해결 방법으로는 해당 헤더를 준수하고, 재시도 사이에 지수 백오프를 추가하고, 요청 횟수를 줄이기 위해 응답을 캐싱하거나, 더 높은 할당량을 요청하는 것이 있습니다. 공개 API와 악용 방지를 위한 로그인 엔드포인트에서 흔히 발생합니다. GitHub, Stripe, Twitter/X 등 대부분의 주요 서비스가 API 속도 제한에 429를 사용합니다.

4xx 오류는 클라이언트의 책임입니다. 요청 자체가 잘못되었으므로 동일한 요청을 그대로 재시도해도 소용이 없습니다(400 Bad Request, 401 Unauthorized, 404 Not Found). 5xx 오류는 서버의 책임입니다. 요청은 완전히 유효하지만 서버가 처리에 실패한 것이므로, 서버가 복구되면 동일한 요청이 성공할 수 있습니다(500, 502, 503). 4xx는 요청을 수정하고, 5xx는 서버를 수정하세요. 이 구분은 재시도 로직에 중요합니다. 지수 백오프를 적용하여 5xx에만 재시도하고, 4xx에는 재시도하지 마세요.

핵심 코드는 200 OK(색인하려는 모든 페이지에서 반환해야 함), 301 Moved Permanently(마이그레이션 시 새 URL로 순위 전달), 302 Found(임시 이동 — 원래 URL의 순위 유지), 404 Not Found와 410 Gone(페이지 누락을 크롤러에 알림. 410이 더 빨리 색인에서 제거되는 이유는 영구적으로 사라졌음을 명확히 하기 때문), 503 Service Unavailable(계획된 점검을 위한 SEO 안전 코드 — 크롤러에게 나중에 다시 오도록 지시하여 페이지 색인 제거 방지)입니다.

401 Unauthorized는 실제로 '미인증' 상태를 의미합니다. 신원을 증명하지 않은 것이므로 유효한 인증 정보(토큰, API 키, 로그인 세션)를 제공하면 해결할 수 있습니다. 서버는 WWW-Authenticate 헤더로 응답해야 합니다. 403 Forbidden은 인증은 되어 있지만 해당 리소스에 접근할 권한이 없다는 의미입니다. 더 좋은 인증 정보를 제공해도 소용이 없으며, 다른 권한이 필요합니다. 간단히 말해 401은 '당신이 누구인지 모름', 403은 '그것을 할 수 없음'입니다.

네 가지 모두 리디렉션이지만, 307과 308은 원래 HTTP 메서드와 본문이 보존됨을 보장합니다. 반면 301과 302는 역사적으로 클라이언트가 리디렉션 요청에서 POST를 GET으로 전환하는 것을 허용합니다. 따라서 301(영구)과 302(임시)는 일반 페이지 리디렉션에는 문제없지만, POST나 PUT 데이터를 수신하는 엔드포인트에서는 메서드를 유지하고 데이터 손실을 방지하기 위해 영구 이동에는 308, 임시 이동에는 307을 사용해야 합니다.

520–530 범위의 코드는 Cloudflare와 오리진 서버 사이에서 문제가 발생했을 때 Cloudflare가 반환하는 비표준 코드입니다. 공식 HTTP 스펙에는 없지만 Cloudflare 뒤에서는 자주 마주칩니다. 520은 오리진이 빈 응답이나 예기치 않은 응답을 보낸 경우, 521은 오리진이 연결을 거부한 경우(다운되었거나 Cloudflare를 방화벽으로 차단), 522는 TCP 연결 타임아웃, 523은 오리진에 도달 불가, 524는 오리진과 연결은 되었으나 100초 내에 응답하지 않은 경우, 525와 526은 SSL 핸드셰이크 및 인증서 실패, 530은 보통 1xxx 코드와 함께 오는 오리진 DNS 오류입니다. 위 검색창에 이 번호들을 입력하면 원인과 해결 방법을 바로 확인할 수 있습니다.

MDN Web Docs는 권위 있는 스펙 참고서이지만 실시간 검색창이 없고, 클래스 필터도 없으며, 간결한 치트시트 보기도 없습니다. 코드별로 페이지를 하나씩 탐색해야 합니다. httpstatuses.com은 그리드 형태로 코드를 보여 주지만 원인과 실질적인 해결 방법은 다루지 않습니다. restapitutorial.com은 인터랙티브 조회 없이 REST 규칙만 다루고, HTTP.cat은 재미있는 밈 사이트(각 코드가 고양이 사진에 대응)지만 실제 디버깅에는 실용적이지 않습니다. 이 도구는 검색 가능한 참고서, 클래스 필터, 치트시트 모드, 명확한 한국어 원인·해결 방법, Cloudflare 5xx 코드, RFC 링크를 한 페이지에서 광고와 회원가입 없이 오프라인으로 제공합니다.

완전히 무료이며 개인 정보도 안전합니다. 전체 목록이 페이지 내부에 정적 데이터로 탑재되어 있어 모든 검색, 필터, 조회가 브라우저 내에서 로컬로 실행됩니다. 어떤 정보도 업로드되거나, 기록되거나, 서버로 전송되지 않습니다. 페이지가 열리면 즉시 로드되고 오프라인에서도 작동합니다. 회원가입, 계정, 이용 횟수 제한, 유료 기능이 없습니다. 스마트폰에서도 데스크톱만큼 빠르고 개인 정보를 지키며 사용할 수 있는 참고서입니다.