HTTP 상태 코드 한눈에: 200·301·401·403·404·500의 진짜 의미

HTTP 상태 코드는 서버가 클라이언트에게 보내는 한 줄 요약입니다. 의미를 정확히 쓰면 디버깅과 API 사용성이 크게 좋아집니다.

큰 그림: 앞자리로 분류

분류	의미
2xx	성공
3xx	리다이렉트(추가 동작 필요)
4xx	클라이언트 잘못(요청이 문제)
5xx	서버 잘못(처리 중 오류)

앞자리만 봐도 책임 소재가 보입니다. 4xx는 보낸 쪽, 5xx는 받은 쪽 문제입니다.

200 vs 201 vs 204

• 200 OK: 일반 성공(본문 포함)
• 201 Created: 리소스 생성 성공. POST 후 Location 헤더로 새 리소스 위치를 알려줌
• 204 No Content: 성공했지만 보낼 본문 없음. DELETE 응답에 잘 어울림

301 vs 302 (리다이렉트의 함정)

• 301 Moved Permanently: 영구 이동. 브라우저·검색엔진이 캐싱하고 링크 평가를 새 URL로 옮김
• 302 Found: 임시 이동. 원래 URL을 유지

SEO에서 도메인/경로를 영구 변경했다면 반드시 301을 써야 검색 순위가 새 URL로 승계됩니다. 임시 점검 페이지라면 302가 맞습니다.

401 vs 403 (가장 자주 헷갈림)

• 401 Unauthorized: "당신이 누구인지 모릅니다." 인증(로그인) 안 됨 → 토큰/로그인 필요
• 403 Forbidden: "당신이 누구인지는 알지만, 권한이 없습니다." 로그인은 됐는데 접근 불가

쉽게: 401은 인증 문제, 403은 인가(권한) 문제입니다.

404 vs 410

• 404 Not Found: 리소스를 찾을 수 없음(있을 수도, 없을 수도)
• 410 Gone: 의도적으로 영구 삭제됨. 검색엔진에 "이제 색인 빼라"는 더 강한 신호

5xx: 서버가 사과할 차례

• 500 Internal Server Error: 잡지 못한 예외 등 일반 서버 오류
• 502 Bad Gateway: 게이트웨이/프록시가 상류 서버에서 잘못된 응답을 받음
• 503 Service Unavailable: 일시적 과부하/점검. Retry-After 헤더로 재시도 시점 안내

마무리 체크리스트

• 생성은 201+Location, 빈 성공은 204
• 영구 이동은 301(SEO 승계), 임시는 302
• 401=인증, 403=권한
• 점검은 503+Retry-After

상태 코드를 정확히 쓰는 API는 문서를 안 봐도 행동을 예측할 수 있습니다.