---

🚦 Response Status Code

HTTP 통신에서 Status Code는 서버가 클라이언트에게 보내는 “결과 신호”다.

우리가 식당에서 주문하면

• “주문 완료요”
• “재료가 없어요”
• “잠시만 기다려주세요”

같은 말로 상황을 전달하듯, 서버도 요청 처리 결과를 숫자 코드로 알려준다.

---

📡 Status Code란?

Status Code는 3자리 숫자로 구성되어 있으며, 요청이 어떤 상태로 처리되었는지를 나타낸다.

중요한 점은 이것이다.

즉,

• Response Body → 데이터 내용
• Status Code → 처리 결과 상태

이 둘은 항상 함께 움직이지만 의미는 전혀 다르다.

---

🔍 FastAPI에서 Status Code 직접 확인해보기

먼저 가장 기본적인 FastAPI 코드를 보자.

from fastapi import FastAPI 
app = FastAPI() 
@app.get("/") 
async def read_root(): 
	return {"message": "Hello"}

이 API를 호출하면 어떤 상태 코드가 나올까?

이번에는 상태 코드를 명시적으로 지정해보자.

@app.post("/items/", status_code=201) 
async def create_item(name: str): return {"name": name}

이 API는 다음을 의미한다.

• 요청 성공
• 새로운 리소스 생성 완료

그래서 201 Created가 반환된다.

---

📖 HTTP 상태 코드의 큰 분류

HTTP 상태 코드는 첫 번째 숫자에 따라 의미가 나뉜다.

범위	의미	설명
1xx	정보	요청을 받았고 처리 중
2xx	성공	요청이 정상 처리됨
3xx	리다이렉션	다른 위치로 이동 필요
4xx	클라이언트 오류	요청 자체에 문제 있음
5xx	서버 오류	서버 내부 문제

---

✅ 2xx: 성공 응답

2xx는 “요청이 잘 처리되었다”는 의미다.

코드	이름	의미	주 사용 상황
200	OK	요청 성공	조회, 수정
201	Created	리소스 생성 완료	POST
204	No Content	성공했지만 반환 데이터 없음	DELETE

---

🚫 4xx: 클라이언트 오류

4xx는 “요청한 쪽(클라이언트)에 문제가 있다”는 뜻이다.

코드	이름	의미	대표 상황
400	Bad Request	잘못된 요청	요청 데이터 오류
401	Unauthorized	인증 필요	로그인 안 됨
403	Forbidden	권한 없음	접근 불가
404	Not Found	리소스 없음	ID 없음

---

🧠 HTTP 상태 코드를 왜 신경 써야 할까?

상태 코드는 단순한 숫자가 아니다.

프론트엔드, 모바일 앱, 다른 서버들은 Status Code를 기준으로 로직을 분기한다.

• 200 → 정상 화면
• 401 → 로그인 페이지 이동
• 403 → 권한 없음 메시지
• 404 → “존재하지 않음” 안내

---

---

🧩 상태 코드 흐름으로 이해하기

상태 코드는 단독으로 보면 감이 잘 안 온다.
요청 → 판단 → 응답 흐름으로 보면 명확해진다.

 
  클라이언트 요청
	↓ 
  요청 데이터 검증
	↓ 
     인증 확인
	↓ 
     권한 확인
	↓
    리소스 존재 여부
	↓
     정상 처리 

단계	문제 발생 시	반환 코드
요청 데이터 오류	형식/값 잘못됨	400
인증 안 됨	로그인 필요	401
권한 없음	접근 불가	403
리소스 없음	ID 없음	404
정상 처리	-	200 / 201 / 204

---

⚙️ FastAPI에서 상태 코드 지정하는 방법

① 숫자로 직접 지정

@app.post("/items/", status_code=201)
async def create_item(name: str):
    return {"name": name}

② status 상수 사용 (권장)

from fastapi import FastAPI, status

app = FastAPI()

@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
    return {"name": name}

@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_item(item_id: int):
    return None

---

---

📚 CRUD와 상태 코드 매핑

작업	HTTP 메서드	권장 상태 코드
Create	POST	201 Created
Read	GET	200 OK
Update	PUT / PATCH	200 OK
Delete	DELETE	204 No Content

---

🧾 최종 정리

• Status Code는 서버의 처리 결과 신호다
• Response Body와는 완전히 다른 레이어다
• 2xx는 성공, 4xx는 클라이언트 오류
• 의미에 맞는 코드를 쓰는 것이 곧 API 설계다