[HTTP 상태 코드] 웹 통신의 응답 언어를 이해하기

728x90

HTTP 상태 코드 

웹에서 클라이언트(예: 브라우저, 앱)와 서버가 통신할 때, 서버는 요청에 대한 응답으로 HTTP 상태 코드를 함께 반환합니다. 이 상태 코드는 요청이 성공했는지, 실패했는지, 왜 실패했는지를 숫자로 요약해 알려주는 일종의 약속입니다.

이 글에서는 HTTP 상태 코드의 5가지 분류, 자주 쓰이는 코드의 의미, 그리고 API 개발 시 올바른 상태 코드 사용법까지 정리해드립니다.

 

---

1.  HTTP 상태 코드란?

HTTP 상태 코드는 서버가 클라이언트의 요청을 어떻게 처리했는지 나타내는 3자리 숫자입니다.

200 OK           → 정상 처리됨
404 Not Found    → 요청한 리소스를 찾을 수 없음
500 Internal Server Error → 서버 오류 발생

상태 코드의 5가지 범주

코드 범위	의미	예시
1xx	정보 (처리 중)	100 Continue
2xx	성공 (요청 처리 완료)	200 OK, 201 Created
3xx	리다이렉션 (다른 위치로 이동)	301 Moved Permanently, 302 Found
4xx	클라이언트 오류 (요청이 잘못됨)	400 Bad Request, 404 Not Found
5xx	서버 오류 (서버 문제로 실패)	500 Internal Server Error, 503 Service Unavailable

 

---

2.  가장 자주 사용하는 HTTP 상태 코드 정리

a.  1xx : 정보 응답 (Informational)

요청을 정상적으로 처리 중이며, 계속 진행하라는 의미를 전달합니다.

클라이언트가 요청을 끝까지 보내도 된다는 신호로 사용됩니다.

코드	설명	사용 예
100 Continue	요청 헤더를 받은 상태, 본문 전송을 계속하라는 의미	대용량 PUT/POST 요청 전에 사용 가능
101 Switching Protocols	서버가 프로토콜 전환 요청을 승인함	HTTP → WebSocket 같은 업그레이드
102 Processing (WebDAV)	서버가 요청을 처리 중이지만 응답은 아직 아님	여러 단계 작업이 필요한 API 요청 시

b.  2xx : 성공 (Success)

요청을 정상적으로 수신하고 이해했으며, 문제 없이 처리되었음을 의미합니다.

성공한 요청에 대한 최종 응답을 나타냅니다.

코드	설명	사용 예
200 OK	요청이 정상적으로 처리됨	일반적인 GET/POST 성공
201 Created	새 리소스가 생성됨	POST 요청으로 회원가입, 글 작성 등
204 No Content	성공했지만 응답 본문 없음	삭제 성공, 토글 요청 등

c.  3xx : 리다이렉션 (Redirection)

3xx 상태 코드는 클라이언트에게 다른 위치로 이동하라는 뜻입니다.
웹 페이지의 주소가 변경되었거나, 리소스가 새 URL로 옮겨졌을 때 사용합니다.

코드	설명	사용 예
301 Moved Permanently	리소스가 영구적으로 이동함	사이트 주소 영구 이전
302 Found	임시 이동	로그인 후 홈으로 리디렉션 시
303 See Other	GET 방식으로 다른 URL 요청하라는 응답	POST 후 리디렉션에 주로 사용
304 Not Modified	리소스가 변경되지 않음 → 클라이언트 캐시 사용	캐시 최적화, If-Modified-Since 응답
307 Temporary Redirect	302와 유사하지만 요청 메서드 유지	POST 요청 후 임시 리디렉션
308 Permanent Redirect	301과 유사하지만 요청 메서드 유지	PUT 요청 등에서 안전한 영구 이동

d.  4xx : 클라이언트 오류 (Client Error)

요청에 문법적인 오류가 있거나, 권한이 없거나, 존재하지 않는 리소스를 요청했을 때 반환됩니다.

클라이언트 측의 잘못으로 서버가 요청을 수행할 수 없음을 나타냅니다.

코드	설명	사용 예
400 Bad Request	잘못된 요청 (문법 오류 등)	필수 필드 누락, 잘못된 JSON
401 Unauthorized	인증 필요	로그인되지 않은 사용자 접근 시
403 Forbidden	접근 권한 없음	권한 없는 유저의 관리자 기능 호출
404 Not Found	요청한 리소스가 없음	존재하지 않는 게시글 ID
409 Conflict	요청 충돌	이미 존재하는 이메일로 회원가입 시

e.  5xx : 서버 오류 (Server Error)

클라이언트의 요청은 타당하지만, 서버가 내부 문제로 요청을 처리하지 못했을 때 반환됩니다.

즉, 문제는 클라이언트가 아닌 서버에 있음을 나타냅니다.

코드	설명	사용 예
500 Internal Server Error	서버 내부 오류	코드 에러, 예외 처리 누락 등
502 Bad Gateway	게이트웨이 서버가 잘못된 응답 수신	프록시 서버 오류 등
503 Service Unavailable	서비스 일시 중단	서버 과부하, 점검 중 등

 

---

3.  상태 코드는 API 설계의 언어다.

HTTP 상태 코드는 단순한 숫자가 아니라, 서버와 클라이언트가 대화하는 방식입니다.

예시

• 로그인 실패 시 단순히 400을 보내는 것보다, 401 Unauthorized를 보내면 클라이언트는 정확히 인증 문제임을 알 수 있습니다.
• 새로운 글을 작성한 후에는 201 Created와 함께 새 글의 URL을 Location 헤더에 포함시킬 수 있습니다.

올바른 상태 코드 사용 예시 (Node.js + Express)

// 글 조회
app.get('/posts/:id', (req, res) => {
  const post = findPost(req.params.id);
  if (!post) {
    return res.status(404).json({ message: 'Post not found' });
  }
  res.status(200).json(post);
});

// 글 생성
app.post('/posts', (req, res) => {
  const newPost = createPost(req.body);
  res.status(201).json(newPost);
});

상태 코드 활용 팁

• 성공 응답은 반드시 200만 사용할 필요는 없습니다. — 201, 204 적극 활용하기
• 에러 응답에는 명확한 메시지와 함께 알맞은 4xx/5xx 코드 사용합시다.
• 클라이언트에서 응답 코드를 기준으로 로직 분기 처리 가능합니다.

 

---

4.  마무리

• HTTP 상태 코드는 클라이언트에게 서버 응답의 상태를 알려주는 숫자 코드입니다.
• 5개 범주로 구분 : 정보(1xx), 성공(2xx), 리다이렉션(3xx), 클라이언트 오류(4xx), 서버 오류(5xx)
• API 개발 시 상태 코드 설계는 명확하고 일관되게 작성해야 합니다.

함께 보면 좋은 자료

외부 사이트 :

• MDN Web Docs - HTTP 상태 코드

블로그 글 :

[RESTful API] 웹 서비스를 설계하는 가장 보편적인 방식

[HTTP 메소드] 웹의 동작 방식을 이해하는 첫걸음

 

---