모든 HTTP 상태 코드를 검색하고 쉽게 설명합니다.
마지막 업데이트
Coddy는 브라우저에서 실제 코드를 작성하며 배웁니다. 인터랙티브 레슨, 즉각적인 피드백, 막힐 때 도와주는 AI까지.
HTTP 상태 코드는 서버가 응답 맨 앞에 붙여 보내는 세 자리 숫자로, 요청이 어떻게 처리됐는지를 한마디로 요약해 줍니다. 브라우저, 클라이언트, 프록시, CDN 등이 캐시할지, 리다이렉트할지, 재시도할지, 아니면 사용자에게 에러를 보여줄지를 이 숫자를 보고 결정합니다.
모든 상태 코드는 첫 번째 숫자에 따라 다섯 가지 클래스로 나뉩니다. 1xx은 정보 전달, 2xx은 성공, 3xx은 리다이렉션, 4xx은 클라이언트 에러, 5xx은 서버 에러죠. 클래스만 알아도 구체적인 코드를 찾아보기 전에 대략적인 의미는 짐작할 수 있습니다.
실제 서비스에서 자주 쓰는 코드는 200, 201, 204, 301, 302, 304, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503 정도로 많지 않습니다. 각 코드가 *진짜로* 무엇을 의미하는지, 그리고 401 Unauthorized와 403 Forbidden, 301 Moved Permanently와 302 Found처럼 헷갈리는 짝의 차이를 정확히 아는 것 - 이게 백엔드/API 개발자의 내공입니다.
4xx은 클라이언트가 뭔가 잘못한 경우(잘못된 입력, 인증 누락, 존재하지 않는 리소스). 5xx은 클라이언트가 무엇을 했든 서버 쪽에서 실패한 경우.401 vs 403, 301 vs 308, 200 vs 204 - 이 차이는 캐싱과 재시도 동작에 실제로 영향을 줍니다.숫자(404, 429)나 키워드(auth, redirect, rate limit)를 입력하면 일치하는 코드들이 실시간으로 필터링됩니다.
특정 코드를 찾는 게 아니라 둘러보고 싶다면 클래스 칩(1xx, 2xx, 3xx, 4xx, 5xx)으로 목록을 좁히세요.
각 항목에는 어떤 상황에서 이 코드가 보내지는지, 클라이언트는 보통 어떻게 동작하는지, 가장 흔한 원인은 무엇인지가 정리돼 있습니다.
헷갈리는 짝(401 vs 403, 301 vs 302)은 see-also 링크로 이어져 있어서, API에 어떤 코드를 쓸지 고를 때 비교하기 편합니다.
한눈에 보는 다섯 가지 HTTP 상태 코드 클래스와 그 의미. RFC 9110에 정의되어 있고, IANA HTTP Status Code Registry에 등록되어 있습니다.
| 클래스 | 의미 | 주요 코드 |
|---|---|---|
| 1xx 정보(Informational) | 요청 수신, 처리 중 | 100, 101, 103 |
| 2xx 성공(Success) | 요청이 정상적으로 처리됨 | 200, 201, 204, 206 |
| 3xx 리다이렉션(Redirection) | 다른 곳을 참고하라 | 301, 302, 304, 307, 308 |
| 4xx 클라이언트 에러 | 요청 자체에 문제가 있음 | 400, 401, 403, 404, 409, 422, 429 |
| 5xx 서버 에러 | 정상적인 요청인데 서버가 처리에 실패 | 500, 502, 503, 504 |
"잘 처리됐습니다"라는 가장 일반적인 성공 응답. 본문이 함께 옵니다.
요청 결과로 새 리소스가 생성되었다는 뜻. 보통 POST 이후에 사용합니다.
성공했지만 본문이 없음. 반환할 데이터가 따로 없는 DELETE나 PUT 응답에 자주 쓰입니다.
셋 다 성공 코드지만, 응답에 무엇이 실리느냐가 다릅니다. 201에는 새로 생성된 리소스를 가리키는 Location 헤더를 함께 넣어야 하고, 204는 정의상 본문이 비어 있어야 합니다.
영구 리다이렉트. 브라우저와 검색엔진이 이 사실을 기억하므로, 기존 URL은 사실상 죽은 셈이 됩니다.
임시 리다이렉트. 브라우저는 매 요청마다 원래 URL을 다시 확인하고, 북마크도 기존 URL을 그대로 유지합니다.
리소스가 실제로 이전된 경우(브랜드 변경, URL 구조 개편 등)에는 301을 씁니다. A/B 테스트, 로그인 리다이렉트, 점검 페이지처럼 일시적인 경우에는 302를 쓰세요.
다른 자격증명(credential)을 보내면 해결될 가능성이 있는 상황이라면 401을 반환하세요. 어떤 자격증명으로도 접근이 안 되는 상황(이 사용자에게는 그냥 막힌 리소스)이라면 403이 맞습니다.
일반적인 서버 에러 - 코드에서 처리되지 않은 예외가 발생한 경우.
Bad Gateway - 앞단의 프록시(CDN, 로드 밸런서)가 업스트림 서버에 도달하지 못함.
Service Unavailable - 서버는 살아 있지만 과부하 상태이거나 점검 중.
Gateway Timeout - 프록시가 업스트림에 닿긴 했지만 시간 안에 응답을 받지 못함.
모두 서버 에러지만, 디버깅 입장에서는 전혀 다른 이야기입니다. 500은 애플리케이션 문제, 502와 504는 네트워크 경로 문제, 503은 용량(capacity) 문제를 가리킵니다.
{"error": "..."}를 담으면서 200 OK로 응답하기. 상태 코드는 계약의 일부입니다. 클라이언트가 분기할 수 있도록 상황에 맞는 코드(400, 404, 500)를 쓰세요.401을 쓰는 경우. 401은 인증이 안 된 상황을 위한 코드이고, 권한 거부는 403입니다.201과 Location 헤더 대신 200을 쓰는 것.404를 반환하기. 리소스의 존재 자체를 숨기는 효과는 있지만, 정당한 권한을 가진 클라이언트도 혼란스러워합니다. 보통은 403이 더 명확합니다.429 Too Many Requests와 503 Service Unavailable을 혼동하기. 클라이언트별 요청 제한에는 429, 전체 시스템 과부하에는 503을 쓰세요.404 Not Found는 서버가 요청은 이해했지만 해당 URL에 리소스가 존재하지 않는다는 뜻입니다. 보통 경로가 잘못됐거나, 리소스가 삭제됐거나, URL을 잘못 입력한 경우입니다.401 Unauthorized는 아직 인증이 안 된 상태입니다 - 서버가 당신이 누구인지 모릅니다. 403 Forbidden은 인증은 됐지만 해당 리소스에 접근할 권한이 없다는 뜻이고요. 다른 자격증명을 보내면 401은 해결될 수 있지만, 403은 해결되지 않습니다.301 Moved Permanently는 영구 리다이렉트입니다 - 브라우저와 검색엔진이 정보를 갱신합니다. 302 Found는 임시 리다이렉트라서 클라이언트는 계속 원래 URL로 요청합니다. 영구 이전에는 301, 일시적인 우회에는 302를 쓰세요.500 Internal Server Error는 일반적인 서버 측 에러로, 보통 처리되지 않은 예외가 위로 전파됐을 때 발생합니다. 클라이언트는 잘못한 게 없고, 정상적인 요청을 서버가 처리하지 못한 것입니다.200 OK를 보내거나, 모든 에러를 500으로 통일하면 API가 쓰기 어려워집니다. 가장 잘 맞는 구체적인 코드를 고르세요. 클라이언트, 프록시, 모니터링, 재시도 로직이 모두 상태 코드를 보고 분기합니다.429 Too Many Requests는 클라이언트가 요청 제한(rate limit)에 걸렸을 때 보내는 응답입니다. 응답에는 언제 다시 시도해도 되는지를 알려주는 Retry-After 헤더를 함께 넣어주는 것이 좋습니다.