HTTP 상태 코드 참조
📋 포맷/변환HTTP 상태 코드(1xx~5xx) 전체 목록을 검색·필터링하고 의미와 사용 상황을 한눈에 확인할 수 있습니다.
Continue
요청의 일부를 받았으며, 계속 요청해도 됨
Switching Protocols
프로토콜 전환 요청을 수락함
OK
요청 성공
Created
요청 성공, 새 리소스 생성됨
Accepted
요청 수락됨, 처리는 아직 완료되지 않음
No Content
요청 성공, 반환할 콘텐츠 없음
Partial Content
범위 요청 성공, 일부 콘텐츠 반환
Moved Permanently
리소스가 영구적으로 이동됨
Found
리소스가 임시로 이동됨
See Other
다른 URI로 요청해야 함 (GET)
Not Modified
캐시된 버전 사용 가능
Temporary Redirect
임시 리다이렉트 (메서드 유지)
Permanent Redirect
영구 리다이렉트 (메서드 유지)
Bad Request
잘못된 요청 구문
Unauthorized
인증 필요
Forbidden
접근 권한 없음
Not Found
리소스를 찾을 수 없음
Method Not Allowed
허용되지 않은 HTTP 메서드
Request Timeout
요청 시간 초과
Conflict
요청이 현재 상태와 충돌
Gone
리소스가 영구적으로 삭제됨
Payload Too Large
요청 본문이 너무 큼
URI Too Long
URI가 너무 김
Unsupported Media Type
지원하지 않는 미디어 타입
Unprocessable Entity
요청은 이해했으나 처리 불가
Too Many Requests
요청 횟수 초과 (Rate Limit)
Internal Server Error
서버 내부 오류
Not Implemented
요청한 기능을 지원하지 않음
Bad Gateway
게이트웨이가 잘못된 응답 받음
Service Unavailable
서비스 일시적 사용 불가
Gateway Timeout
게이트웨이 응답 시간 초과
🌐 3자리 숫자에 담긴 응답의 의미
HTTP 상태 코드는 서버가 보내는 짧은 답신입니다. 첫 자리만 외워도 절반은 끝. 1xx는 "계속해도 좋다", 2xx는 "성공", 3xx는 "다른 곳으로 가라",4xx는 "네가 잘못했다", 5xx는 "내가 잘못했다"로 외워두면 빠르게 분류됩니다.RFC 9110(2022) 기준 약 60여 개 코드 중 실무에서 자주 마주치는 30여 개를 한 화면에 정리했습니다.
📊 카테고리별 큰 그림
100 Continue, 101 Switching Protocols 등. WebSocket 업그레이드 외에는 거의 안 보임
200 OK가 90% 이상. POST 후엔 201, DELETE 후엔 204를 자주 봄
301(영구)와 302(임시)가 핵심. SEO 관점에선 무조건 301 권장
400/401/403/404가 절대 다수. 429는 Rate Limit이므로 백오프 필요
500은 코드 버그, 502/503/504는 인프라(게이트웨이/스케일링) 문제일 확률이 높음
💡 디버깅할 때 가장 자주 만나는 코드
- 200 OK — 성공. 그러나 응답 본문에 에러 메시지가 들어 있는 케이스(이른바 200 Always)는 의외로 흔하니 항상 바디도 확인.
- 301 / 308 — 영구 리다이렉트. 도메인 이전이나 https 강제 전환 시 사용. 한 번 캐시되면 잘 안 풀리니 신중히.
- 401 vs 403 — 401은 "너 누구?"(인증 부재/실패), 403은 "너 누군지는 알겠는데 권한이 없어".
- 422 Unprocessable Entity — 문법은 맞는데 비즈니스 검증 실패. Rails, Laravel API에서 자주 등장.
- 429 Too Many Requests — 헤더의 Retry-After 값을 보고 정확한 시간만큼 기다린 뒤 재시도.
- 502 Bad Gateway — 업스트림(예: Node 서버)이 죽었거나, nginx 타임아웃 설정이 짧을 가능성.
- 504 Gateway Timeout — 백엔드가 살아 있지만 느림. 쿼리 인덱스, N+1, 외부 API 응답 시간부터 점검.
⚠️ 헷갈리는 조합 체크
401 vs 403: 토큰 부재/만료는 401, 권한 부족은 403. 502 vs 504: 업스트림이 죽었으면 502, 살아있는데 느리면 504. 잘못 매핑하면 모니터링 알람 분류부터 엉킵니다.
자주 묻는 질문
401과 403, 어떻게 구분해서 써야 하나요?▼
클라이언트가 토큰을 안 보냈거나 만료된 경우엔 401, 토큰은 유효한데 해당 리소스에 접근 권한이 없을 땐 403입니다. 보안 관점에서 가끔 일부러 모든 권한 부족을 404로 위장하기도 하지만, 일반적인 비즈니스 API라면 표준대로 401/403을 정확히 나누어 주세요.
302와 307은 둘 다 임시 리다이렉트인데 왜 나뉘어 있나요?▼
역사적 이유로 302는 일부 구현체가 POST를 GET으로 바꿔서 리다이렉트하는 동작을 했고, 그게 호환성 이슈가 되자 RFC 7231이 메서드를 그대로 유지하는 307 Temporary Redirect를 새로 정의했습니다. 폼 제출 후 리다이렉트라면 303 See Other가 가장 안전합니다.
301 영구 리다이렉트, 한 번 걸면 못 되돌리나요?▼
서버 응답을 304가 아닌 301로 바꾸면 되돌릴 수는 있지만, 브라우저와 검색엔진이 일정 시간 결과를 캐시하기 때문에 사용자 입장에선 안 풀린 것처럼 보입니다. 도메인 이전 같은 경우라면 며칠 ~ 몇 주까지 캐시가 남는 경우가 있으니 신중하게 결정하세요.
커스텀 상태 코드를 만들어 써도 되나요?▼
기술적으로는 가능하지만 권장하지 않습니다. 클라이언트 라이브러리나 프록시가 표준 코드만 이해하므로, 비즈니스 의미는 본문(JSON)에 errorCode 필드로 담고 HTTP 코드는 표준 범위 안에서 골라 쓰세요. nginx의 499(클라이언트 종료)나 Cloudflare의 520-527처럼 잘 알려진 벤더 확장은 예외입니다.