레퍼런스 · 2026년 7월 9일 · 읽는 시간 4분
HTTP 상태코드 매번 검색하기 귀찮아서 만든 레퍼런스
422가 Unprocessable Entity인지 415가 Unsupported Media Type인지 매번 헷갈린다.
HTTP 상태코드 레퍼런스가 필요한 상황
개발하면서 자주:
- API 설계 → 어떤 상황에 어떤 코드를 반환할지
- 에러 디버깅 → 받은 코드가 무슨 의미인지
- Postman 테스트 → 응답 코드 의미 확인
- 코드 리뷰 → 적절한 상태코드를 반환하고 있는지
- API 문서 작성 → 응답 코드 목록 작성
상태코드 분류
5가지 그룹으로 나뉜다:
- 1xx (정보) → 요청 처리 중 (잘 안 씀)
- 2xx (성공) → 요청 성공
- 3xx (리다이렉션) → 다른 곳으로 이동
- 4xx (클라이언트 에러) → 요청이 잘못됨
- 5xx (서버 에러) → 서버 문제
자주 쓰는 2xx 코드
- 200 OK → 성공. GET 요청 응답, 수정된 리소스 반환 시
- 201 Created → 리소스 생성 성공. POST로 새 데이터 만들었을 때
- 204 No Content → 성공하지만 응답 본문 없음. DELETE 후, 업데이트 후 본문 필요 없을 때
- 206 Partial Content → 부분 응답. 파일 다운로드 재개, 페이지네이션
자주 쓰는 3xx 코드
- 301 Moved Permanently → 영구 이동. URL 변경 시 SEO 유지용
- 302 Found → 임시 이동. 로그인 후 리다이렉트
- 304 Not Modified → 캐시 사용. If-Modified-Since 헤더 활용
- 307/308 → 301/302와 비슷하지만 메서드 변경 없음
자주 쓰는 4xx 코드
- 400 Bad Request → 잘못된 요청 (파라미터 오류, 유효성 검사 실패)
- 401 Unauthorized → 인증 필요 (토큰 없음, 만료)
- 403 Forbidden → 권한 없음 (인증은 됐지만 권한 부족)
- 404 Not Found → 리소스 없음
- 405 Method Not Allowed → 허용되지 않은 HTTP 메서드
- 409 Conflict → 충돌 (이미 존재하는 데이터, 동시성 충돌)
- 410 Gone → 영구 삭제됨 (404와 달리 의도적 삭제)
- 422 Unprocessable Entity → 문법은 맞지만 의미적 오류 (유효성 검사 실패)
- 429 Too Many Requests → Rate limit 초과
자주 쓰는 5xx 코드
- 500 Internal Server Error → 서버 내부 오류 (예외 처리 안 됨)
- 502 Bad Gateway → 게이트웨이/프록시 서버가 잘못된 응답 받음
- 503 Service Unavailable → 서비스 일시 불가 (배포 중, 과부하)
- 504 Gateway Timeout → 업스트림 서버 응답 시간 초과
헷갈리는 것들
401 vs 403:
- 401 → "누구세요?" (인증 안 됨)
- 403 → "알지만 안 돼요" (인증 됐지만 권한 없음)
400 vs 422:
- 400 → 요청 자체가 잘못됨 (JSON 파싱 오류, 필수 파라미터 없음)
- 422 → 요청 형식은 맞지만 내용이 처리 불가 (이메일 형식 오류, 숫자 범위 초과)
302 vs 307:
- 302 → 임시 이동, POST 요청이 GET으로 바뀔 수 있음
- 307 → 임시 이동, 원래 메서드 유지 (POST는 POST로 리다이렉트)
그래서 만들었음
주요 기능:
- 전체 HTTP 상태코드 목록 (1xx~5xx)
- 코드 번호로 빠른 검색
- 키워드로 검색 (예: "unauthorized", "not found")
- 각 코드별 상세 설명 및 사용 예시
- 언제 써야 하는지 가이드
사용법
- 상태코드 번호 또는 키워드 검색
- 상세 설명과 사용 예시 확인
- API 설계에 적용
써보기
API 개발할 때 옆에 띄워두면 편하다.
#HTTP상태코드 #HTTP #API개발 #RESTful #백엔드개발