🚨 Error Handling – 에러 처리

API를 만들 때 가장 위험한 순간은 에러가 발생했을 때다.

정상 응답은 누구나 신경 쓴다. 하지만 실무의 품질은 에러 처리에서 갈린다.

이번 글에서는 FastAPI에서 에러가 왜 필요한지, HTTPException은 무엇인지, 그리고 “올바른 에러”란 무엇인지를 단계적으로 정리한다.

---

📌 1. 에러(Error)란 무엇인가

프로그래밍에서 에러는 프로그램의 정상적인 흐름이 깨진 상태다.

FastAPI 기준으로 보면, 에러는 크게 두 종류로 나뉜다.

구분	의미	예시
클라이언트 에러	요청이 잘못됨	404, 400
서버 에러	서버 내부 문제	500

중요한 원칙이 하나 있다.

---

📚 2. HTTP 상태 코드 복습

HTTP 상태 코드는 서버가 클라이언트에게 보내는 “결과 요약”이다.

범위	의미	대표 코드
200번대	성공	200 OK, 201 Created
400번대	클라이언트 에러	400, 404
500번대	서버 에러	500

예를 들어,

• 없는 데이터를 요청했다 → 404
• 입력값이 이상하다 → 400
• 코드가 터졌다 → 500

500 에러를 그대로 노출하는 것은 최악이다.

---

🧪 3. 에러 처리 없이 API를 만들면?

일단 아무 에러 처리 없이 API를 하나 만들어보자.

from fastapi import FastAPI

app = FastAPI()

items = {
    "foo": "크아아아아아악!"
}

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    return {"item": items[item_id]}
    

이 상태에서 요청을 보내면 어떻게 될까?

요청	결과
/items/foo	200 OK
/items/bar	500 Internal Server Error

문제는 여기 있다.

이건 완전히 잘못된 API다.

---

🚑 4. HTTPException으로 올바른 에러 처리

FastAPI는 이를 위해 HTTPException이라는 도구를 제공한다.

from fastapi import FastAPI, HTTPException

app = FastAPI()

items = {
    "foo": "크아아아아아악!"
}

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id not in items:
        raise HTTPException(
            status_code=404,
            detail="Item not found"
        )
    return {"item": items[item_id]}

이제 결과는 이렇게 바뀐다.

요청	응답
/items/foo	200 OK
/items/bar	404 Not Found

---

🧠 5. raise vs return

🔸 return

• 함수를 정상 종료
• 이후 코드 실행 가능

🔸 raise

• 즉시 실행 중단
• 상위 호출 스택까지 전파

if user_id <= 0:
    raise HTTPException(
        status_code=400,
        detail="User ID must be positive"
    )

---

📦 6. HTTPException의 구성 요소

raise HTTPException(
    status_code=400,
    detail="Invalid request"
)

필드	역할
status_code	HTTP 상태 코드
detail	클라이언트에게 전달할 메시지

detail에는 문자열뿐 아니라 JSON으로 변환 가능한 모든 값을 넣을 수 있다.

raise HTTPException(
    status_code=404,
    detail={
        "error": "ITEM_NOT_FOUND",
        "message": "아이템을 찾을 수 없습니다"
    }
)

---

🔄 에러 처리 흐름 시각화

  [클라이언트 요청]
        ↓
[엔드포인트 함수 실행]
        ↓
	조건 실패
        ↓
raise HTTPException
        ↓
FastAPI가 응답 생성
        ↓
HTTP 상태 코드 + 에러 메시지
        ↓
	[클라이언트]

---

🧱 7. 사용자 정의 예외 클래스 만들기

🚨 커스텀 예외 핸들러 (Custom Exception Handler)

에러를 if / return으로 처리하기 시작하면 코드는 금방 지저분해지고, 응답 형식도 제각각이 된다.

FastAPI의 전역 예외 핸들러는 이 문제를 구조적으로 해결한다.

🧩 왜 커스텀 예외가 필요한가

• 단순한 404, 400을 넘는 비즈니스 에러가 존재함
• 에러 응답 포맷을 API 전체에서 통일하고 싶음
• 에러 처리 코드가 엔드포인트에 섞이는 걸 막고 싶음

❌ 잘못된 구조
--------------------------------
if 잔액 부족:
    return {"error": "..."}  # 엔드포인트마다 중복

✅ 올바른 구조
--------------------------------
raise CustomException
→ 전역 핸들러에서 응답 생성

---

🧱 사용자 정의 예외 만들기

비즈니스 의미를 담은 예외 클래스를 직접 만든다.

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

# 사용자 정의 예외 클래스
class InsufficientBalanceException(Exception):
    """잔액 부족 예외"""
    def __init__(self, balance: int, required: int):
        self.balance = balance      # 현재 잔액
        self.required = required    # 필요한 금액

app = FastAPI()

# 예외 핸들러 등록
# InsufficientBalanceException이 발생하면 이 함수가 처리함
@app.exception_handler(InsufficientBalanceException)
async def insufficient_balance_handler(
    request: Request, 
    exc: InsufficientBalanceException
):
    return JSONResponse(
        status_code=400,
        content={
            "error": "INSUFFICIENT_BALANCE",
            "message": "잔액이 부족합니다",
            "current_balance": exc.balance,
            "required_amount": exc.required,
            "shortage": exc.required - exc.balance
        }
    )

@app.post("/purchase/{item_id}")
async def purchase_item(item_id: str, user_balance: int = 1000):
    item_price = 1500
    if user_balance < item_price:
        # 커스텀 예외 발생
        raise InsufficientBalanceException(
            balance=user_balance,
            required=item_price
        )
    return {"message": "구매 완료", "remaining": user_balance - item_price}

🧭 예외 흐름

[Client]
   |
   | POST /purchase/item1
   v
[Endpoint]
   |
   | 잔액 체크 (1000 < 1500)
   |
   | raise InsufficientBalanceException
   v
[Exception Handler]
   |
   | JSONResponse 생성
   v
[Client]
  400 Bad Request + 상세 에러

🎯 전역 예외 핸들러의 진짜 가치

이점	설명
중복 제거	모든 엔드포인트에서 에러 처리 로직 제거
일관성	에러 응답 포맷 통일
관심사 분리	비즈니스 로직 ↔ 에러 처리 분리

⚠️ 기본 예외 핸들러 오버라이드

FastAPI는 기본적으로 두 가지를 자동 처리한다.

예외	발생 시점
HTTPException	명시적으로 raise
RequestValidationError	요청 데이터 검증 실패

---

🧪 RequestValidationError 오버라이딩

기본 검증 에러는 사람이 읽기 힘들기 때문에, 응답을 오버라이딩하여 사용한다.

from fastapi import FastAPI, HTTPException
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from starlette.exceptions import HTTPException as StarletteHTTPException

app = FastAPI()

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request, exc: RequestValidationError):
    # 검증 에러를 사용자 친화적인 형식으로 변환
    errors = []
    for error in exc.errors():
        errors.append({
            "field": " → ".join(str(loc) for loc in error["loc"]),
            "message": error["msg"],
            "type": error["type"]
        })
    
    return JSONResponse(
        status_code=422,
        content={
            "error": "VALIDATION_ERROR",
            "message": "입력값이 올바르지 않습니다",
            "details": errors
        }
    )

@app.get("/items/{item_id}")
async def read_item(item_id: int):  # int 타입 기대
    return {"item_id": item_id}

/items/abc 요청 시 기본 응답 vs 커스텀 응답
기본 응답:

{
    "detail": [{
        "loc": ["path", "item_id"],
        "msg": "value is not a valid integer",
        "type": "type_error.integer"
    }]
}

커스텀 응답:

{
    "error": "VALIDATION_ERROR",
    "message": "입력값이 올바르지 않습니다",
    "details": [{
        "field": "path → item_id",
        "message": "value is not a valid integer",
        "type": "type_error.integer"
    }]
}

👌 가독성이 훨씬 좋아진 것을 볼 수 있음.

---

⚡ FastAPI vs Starlette HTTPException

FastAPI의 HTTPException은 Starlette의 HTTPException을 상속받는다.
예외 핸들러를 등록할 때는 Starlette의 HTTPException으로 등록해야 FastAPI 내부 코드나 Starlette 플러그인에서 발생하는 예외도 잡을 수 있다.

구분	FastAPI	Starlette
용도	비즈니스 로직	전역 핸들러
detail 타입	JSON 가능	문자열

---

✅ 체크리스트

• 클라이언트 에러는 400번대 사용
• 500 에러를 그대로 노출하지 않기
• 에러 응답 포맷 통일
• Starlette HTTPException으로 핸들러 등록