HTTP 상태 코드는 모든 응답의 맨 앞에 붙는 세 자리 숫자로, 클라이언트의 요청이 어떻게 처리됐는지 알려 줍니다. 이 레퍼런스는 100 Continue부터 511 Network Authentication Required까지 56개 코드를 골라 쉬운 설명, 사용 시점, 함께 오는 헤더, 캐시 동작, HTTP·Express·Fetch Response·nginx용 복사 스니펫과 함께 정리합니다.
맨 위의 "어떤 상태 코드를 써야 할까요?" 선택기는 서버가 하려는 일(무언가 만들었다, 페이지를 영구 이전했다, 클라이언트를 제한했다, 업스트림이 타임아웃됐다)을 보낼 코드와 이유, 대안으로 바꿔 줍니다. 그 아래에서는 번호 앞부분(4, 40, 404, 4xx), 이름, cache·timeout 같은 설명 속 단어로 검색하고 분류로 거른 뒤 코드를 열어 자세히 볼 수 있습니다. API의 응답 코드를 고르는 개발자와 마주친 오류를 디버깅하는 사이트 운영자를 위한 도구입니다.
목록은 고정되어 있고 검색은 브라우저 안에서 이루어집니다. IANA 전체 레지스트리가 아니라 실무용 선별 목록입니다. 거의 쓰이지 않는 WebDAV·협상 코드 102, 208, 226, 506, 사용 중단이 권고된 305, 폐기된 510은 뺐고, 418은 RFC 9110에서 (Unused)로 예약됐지만 알아볼 수 있도록 포함했습니다.
사용 방법
선택기로 묻거나 검색
"어떤 상태 코드를 써야 할까요?"에서 서버가 하려는 일을 고르거나,
40같은 번호 앞부분,429같은 전체 코드,gateway같은 이름 일부,cache같은 설명 속 단어를 입력합니다. 대소문자는 구분하지 않습니다.종류로 좁히기
분류 칩으로 자주 쓰는 코드만, 또는 1xx, 2xx, 3xx, 4xx, 5xx 중 한 분류만 볼 수 있습니다.
의미와 조언 읽기
코드를 선택하면 의미, 사용 시점, 보통 함께 오는 헤더, 기본 캐시 가능 여부, 리다이렉트가 요청 메서드를 다루는 방식이 나옵니다.
비슷한 코드 비교와 스니펫 복사
"자주 헷갈리는 코드" 목록이 401·403이나 301·308 같은 쌍의 차이를 한 줄로 설명하고 상대 코드로 이동시켜 줍니다. 고른 코드의 HTTP, Express, Response, nginx 스니펫을 복사하세요.
작동 원리
다섯 가지 클래스
RFC 9110(HTTP Semantics)은 첫 자리 숫자를 응답의 클래스로 정의합니다. 클라이언트는 모르는 코드를 해당 클래스의 x00 코드로 취급해야 하므로, 알 수 없는 499는 400처럼 처리됩니다.
| 클래스 | 범위 | 의미 |
|---|---|---|
| Information | 1xx | 요청을 받았고 처리가 계속됨 |
| Success | 2xx | 요청을 받았고 이해했고 수락함 |
| Redirection | 3xx | 클라이언트가 추가 동작을 해야 함, 보통 Location을 따라감 |
| Client error | 4xx | 요청이 잘못되었거나 권한을 인정할 수 없음 |
| Server error | 5xx | 유효한 요청을 서버가 처리하지 못함 |
헷갈리기 쉬운 코드 고르기
리다이렉트: 301과 308은 영구, 302와 307은 임시입니다. 301과 308(302와 307)의 차이는 메서드입니다. 역사적으로 브라우저는 301·302 뒤에 POST를 GET으로 바꾸고, 307·308은 같은 메서드와 본문으로 다시 요청해야 합니다. POST가 리다이렉트 뒤에도 유지되어야 하면 307이나 308을 쓰세요.
인증: 401은 유효한 자격 증명이 없다는 뜻이며 클라이언트가 자격 증명을 갖춰 다시 시도할 수 있도록 WWW-Authenticate 헤더를 함께 보내야 합니다. 403은 서버가 요청을 이해했지만 거부한다는 뜻입니다. 404는 서버가 리소스의 존재 자체를 숨기고 싶을 때도 쓰는 코드입니다.
검증: 파싱할 수 없는 요청은 400, 형식은 맞지만 검증 규칙을 어기는 요청은 422 Unprocessable Content, 중복이나 오래된 버전처럼 리소스의 현재 상태와 충돌하는 요청은 409 Conflict입니다.
서버 측 장애와 재시도
500은 일반적인 실패입니다. 502 Bad Gateway와 504 Gateway Timeout은 프록시나 로드 밸런서가 보내며, 502는 업스트림이 잘못된 응답을 했거나 연결을 끊은 경우, 504는 제때 응답하지 않은 경우입니다. 503 Service Unavailable은 과부하나 점검 같은 일시적 상태를 알리며 Retry-After 헤더를 달 수 있습니다. 429 Too Many Requests는 요청 제한이며 가능하면 마찬가지로 Retry-After를 보냅니다.
검색엔진에서는 이 차이가 중요합니다. 5xx나 429 응답은 구글이 크롤링 속도를 줄이고 나중에 다시 시도하게 하고, 301은 이전 URL의 신호를 새 URL로 넘기며, 404 페이지가 200을 반환하는 경우(소프트 404)는 크롤링 자원을 낭비하고 색인을 혼란스럽게 합니다.
실제 예시
검색어: 404, 종류: 전체404 Not Found (클라이언트 오류)
의미: 요청한 리소스를 찾을 수 없습니다.
언제: 알 수 없는 URL, ID, 라우트입니다.
캐시: 기본적으로 캐시 가능
스니펫: HTTP/1.1 404 Not Found페이지 언어에 맞춰 설명이 한국어로 표시됩니다. 상태 코드 이름은 로그와 문서에 나오는 영어 표준 이름 그대로입니다.
검색어: redirect, 종류: 전체307 Temporary Redirect
308 Permanent Redirect이름과 설명을 모두 검색합니다. 301과 302는 설명에 redirect 대신 "영구 URL", "다른 URL"이라고 되어 있어 나오지 않습니다. 3xx 칩을 고르면 모든 리다이렉트 코드를 볼 수 있습니다.
검색어: cache, 종류: 전체304 Not Modified (리다이렉트)
캐시된 사본이 아직 유효해서 본문을 보내지 않습니다.304는 리다이렉트가 아니지만 3xx 클래스에 속합니다. 클라이언트에게 캐시된 사본을 다시 쓰라고 알립니다.
검색어: 40, 분류: 4xx 클라이언트 오류10개: 400 Bad Request, 401 Unauthorized, 402 Payment Required, 403 Forbidden, 404 Not Found, 405 Method Not Allowed, 406 Not Acceptable, 407 Proxy Authentication Required, 408 Request Timeout, 409 Conflict번호는 앞에서부터 맞춥니다. 4는 모든 4xx 코드, 40은 40x 코드, 404는 정확히 하나를 보여 주며 4xx도 됩니다.
자주 하는 실수
오류에 200 사용
200을 반환하는 오류 페이지는 클라이언트, 모니터링, 검색엔진을 모두 헷갈리게 합니다. 오류 본문과 함께 실제 상태 코드를 반환하세요.
401과 403 혼동
401은 자격 증명이 없거나 잘못된 경우,403은 권한이 없는 경우입니다. 로그인하지 않았을 뿐인 사용자에게 403을 주면 로그인하라는 단서가 사라집니다.임시인데 영구 리다이렉트를 쓴 경우
브라우저와 검색엔진은 301과 308을 강하게 캐시합니다. 대상이 바뀔 수 있다면 302나 307을 쓰고, 확실해진 뒤에만 영구 코드로 바꾸세요.
클라이언트 실수에 500 반환
잘못된 입력은 클라이언트의 오류이므로 4xx에 속합니다. 잘못된 입력에 500을 주면 알림 대시보드가 넘치고 클라이언트는 재시도하면 될 것으로 오해합니다.
Retry-After 누락
429와 503은
Retry-After헤더가 있으면 훨씬 유용합니다. 예의 바른 클라이언트와 크롤러가 언제 다시 올지 알 수 있습니다.
자주 묻는 질문
301과 302의 차이는 무엇인가요?
301은 이동이 영구적이라는 뜻이어서 클라이언트와 검색엔진이 예전 URL을 새 URL로 바꿉니다. 302는 임시 이동이라 원래 URL을 계속 쓰라는 뜻입니다.
401과 403의 차이는 무엇인가요?
401은 인증이 없거나 실패했다는 뜻이고, 403은 요청을 이해했지만 서버가 거부한다는 뜻입니다. 401 응답에는 WWW-Authenticate 헤더가 있어야 합니다.
502 Bad Gateway는 무슨 뜻인가요?
게이트웨이나 프록시가 전달 대상인 업스트림 서버에서 잘못된 응답을 받았거나 아무 응답도 받지 못했다는 뜻입니다. 업스트림 서비스, 프록시 설정, 타임아웃을 점검하세요.
400 대신 422는 언제 쓰나요?
요청이 잘못된 형식이라 파싱할 수 없으면 400, 파싱은 잘 되지만 값이 비즈니스·검증 규칙을 어기면 422 Unprocessable Content를 씁니다.
DELETE가 성공했을 때 204가 맞나요?
맞습니다. 204 No Content는 본문 없이 성공을 알리므로 삭제나, 아무것도 돌려주지 않는 수정에 어울립니다.
모든 상태 코드가 들어 있나요?
아니요. 410 Gone, 451, 507을 포함한 코드 56개를 선별했습니다. 418도 식별할 수 있도록 넣었지만 RFC 9110에서는 (Unused)로 예약돼 있습니다. 등록 코드 102, 208, 226, 506과 사용 중단이 권고된 305, 폐기된 510은 다루지 않습니다.
검색어가 어딘가로 전송되나요?
아니요. 목록은 페이지에 내장되어 있고 필터링은 브라우저 안에서 이루어집니다.
마지막 업데이트: