🚨 FastAPI에서의 예외 처리 완전 정복 - nojamlog (life is boring but let's find fun!)

Table of Contents

🕒 약 1분 읽는 데 소요됩니다

– HTTPException부터 커스텀 예외 핸들러까지 한 번에 익혀보자

“에러는 숨기지 말고 명확하게 다뤄야 한다.”
FastAPI는 에러 처리 또한 모던하고 깔끔하게 제공한다. 단순히 서버에서 터지는 오류를 방지하는 것뿐 아니라, 클라이언트에게 유용한 에러 메시지를 반환하고, API의 신뢰성을 높이는 방식으로 접근해야 한다.

✅ 예외 처리 기본 구조

FastAPI는 내부적으로 Python의 예외 시스템을 그대로 사용한다. 여기에 웹 표준인 HTTP 상태 코드를 접목시켜 HTTPException이라는 예외 클래스를 제공한다.

1. 가장 기본적인 예외 처리 방법

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id > 100:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item_id": item_id}

HTTPException은 FastAPI가 제공하는 예외 클래스이다.
status_code는 반환할 HTTP 상태 코드이다.
detail은 클라이언트에게 제공할 에러 메시지이다.

이렇게 작성하면 item_id가 100을 초과할 경우 클라이언트는 404 에러와 함께 "Item not found" 메시지를 받게 된다.

🚦 다양한 HTTP 상태 코드 사용해보기

FastAPI에서는 표준 HTTP 상태 코드를 마음대로 사용할 수 있다. 자주 사용하는 몇 가지 상태 코드는 아래와 같다.

상태 코드	의미
400	Bad Request – 잘못된 요청이다
401	Unauthorized – 인증이 필요하다
403	Forbidden – 접근이 금지되었다
404	Not Found – 자원을 찾을 수 없다
500	Internal Server Error – 서버 내부 오류이다

사용 예는 다음과 같다.

if not authorized:
    raise HTTPException(status_code=401, detail="로그인이 필요합니다.")

이렇게 상황에 따라 적절한 상태 코드를 사용하면 클라이언트 입장에서도 API의 의도를 더 잘 이해할 수 있다.

🧰 추가 필드: headers, content

HTTPException은 단순히 상태 코드와 메시지만 전달하는 것이 아니다. 필요하다면 응답 헤더나 상세 내용을 더 추가할 수 있다.

raise HTTPException(
    status_code=403,
    detail="Access denied",
    headers={"X-Error": "Permission denied"}
)

위 예시처럼 헤더에 X-Error를 추가해 클라이언트 측에서 로깅이나 트래킹에 사용할 수도 있다.
보안이나 사용성 측면에서 유용하게 활용할 수 있다.

🛠 커스텀 예외 핸들러 작성하기

어떤 예외든지 우리가 직접 처리 로직을 정의하고 싶을 때가 있다. 예를 들어 데이터베이스 오류나 사용자 정의 에러가 발생했을 때, 모든 예외를 공통된 형식으로 응답하고 싶다면 **커스텀 예외 핸들러(Custom Exception Handler)**를 사용할 수 있다.

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

class MyCustomException(Exception):
    def __init__(self, name: str):
        self.name = name

일반적인 Python 예외 클래스를 만든다.
필요에 따라 파라미터를 넘기거나 메시지를 설정할 수 있다.

2. 예외 핸들러 등록하기

FastAPI에서는 @app.exception_handler() 데코레이터를 통해 예외를 핸들링할 수 있다.

from fastapi.responses import JSONResponse
from fastapi.requests import Request

@app.exception_handler(MyCustomException)
async def my_exception_handler(request: Request, exc: MyCustomException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops! {exc.name}이라는 에러가 발생했습니다."}
    )

Request 객체와 발생한 예외 exc를 인자로 받는다.
JSON 형식으로 응답을 직접 구성할 수 있다.
이 방식으로 모든 사용자 정의 예외를 공통 포맷으로 출력할 수 있다.

📌 예: 커스텀 예외를 실제 API에 적용해보자

@app.get("/error-test/{name}")
def error_test(name: str):
    if name == "bad":
        raise MyCustomException(name)
    return {"name": name}

/error-test/bad로 요청하면 우리가 정의한 MyCustomException이 발생한다.
이 예외는 앞서 등록한 핸들러에서 자동으로 처리된다.
클라이언트는 상태 코드 418과 함께 "Oops! bad이라는 에러가 발생했습니다." 메시지를 받게 된다.

🤹 예외 처리 팁과 주의사항

가능한 모든 예외를 핸들링하자.
- FastAPI는 기본적으로 예외를 JSON 형태로 반환하지만, 명확한 메시지를 직접 전달해주는 것이 훨씬 좋다.
공통 오류 포맷을 사용하자.
- API에서 일관된 형태의 에러 메시지를 제공하면 클라이언트 측에서 파싱과 처리도 쉬워진다.
예외 메시지에 민감한 정보는 담지 말자.
- DB 쿼리 오류나 시스템 메시지를 그대로 노출하면 보안상 위험하다.
테스트를 통해 모든 경로에서 예외가 잘 발생하는지 확인하자.
- 예외 처리가 잘못되면 500 오류로 넘어가 사용자는 이유를 알 수 없다.

🧾 정리해보자

FastAPI의 에러 처리 방식은 단순한 예외 발생을 넘어, 웹 서비스 전반의 신뢰성과 품질을 향상시키는 도구이다. HTTPException은 즉각적인 오류 응답에 좋고, 커스텀 예외 핸들러는 복잡한 로직에 유연하게 대응할 수 있게 도와준다.

기능	사용법	목적
`HTTPException`	`raise HTTPException(status_code, detail)`	빠른 HTTP 오류 반환
커스텀 예외 클래스	`class MyException(Exception)`	사용자 정의 로직 표현
커스텀 핸들러	`@app.exception_handler(MyException)`	예외 메시지 커스터마이징

FastAPI에서는 예외가 곧 사용자 경험이다. 어떻게 에러를 전달할지에 따라 서비스의 전문성이 드러난다.
다음 단계로 넘어가기 전에, 자신이 만든 모든 API 라우트에 올바른 예외 처리가 있는지 다시 한 번 점검해보자.

FastAPI 공식 문서 : https://fastapi.tiangolo.com/ko/