응답 상태 코드

응답 상태 코드 (Response Status Code)

API가 요청을 처리하고 나면 그 결과를 나타내는 숫자, HTTP 상태 코드를 돌려줘요. FastAPI는 응답 모델을 지정할 수 있듯이, 경로 동작 마다 이 상태 코드도 함께 선언할 수 있게 해 줘요. 기본적으로는 200("OK")이 사용되지만, 대부분의 API는 상황에 맞는 상태 코드를 직접 골라줘야 해요.

출처: 공식문서

status_code로 상태 코드 지정하기

모든 경로 동작(@app.get(), @app.post(), @app.put(), @app.delete() 등)에서 status_code 파라미터로 응답에 쓸 HTTP 상태 코드를 선언할 수 있어요.

예를 들어 새 아이템을 만드는 POST 동작이라면, 성공적으로 만들었을 때 201 "Created"가 어울리겠죠.

from fastapi import FastAPI

app = FastAPI()


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

참고

status_code 자리에 정수 대신 IntEnum, 예를 들어 Python 표준 라이브러리의 http.HTTPStatus를 넘길 수도 있어요.

상태 코드를 이렇게 지정하면 FastAPI는 두 가지를 해 줘요.

  • 응답에 그 상태 코드를 그대로 돌려줘요.
  • OpenAPI 스키마(그리고 그걸 쓰는 문서 UI)에 그대로 기록해요.

상태 코드가 의미를 갖는 만큼, 숫자보다 이름이 더 읽기 쉬울 때도 있어요. 그래서 FastAPI는 status 모듈에 상수를 준비해 뒀어요. status.HTTP_201_CREATED처럼 쓰면 숫자 201과 완전히 같답니다.

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}

HTTP 상태 코드에 대해

몇 가지만 기억하면 상태 코드가 훨씬 친숙해져요.

  • 100 - 199는 정보(Informational) 응답이에요.
  • 200 - 299는 성공(Success) 응답이에요.
    • 201 "Created"는 대표적인 예로, 데이터베이스에 새 레코드를 만든 뒤 흔히 쓰여요.
    • 특별한 경우로 204 "No Content"가 있어요. 클라이언트에게 돌려줄 내용이 없을 때 쓰는 응답이라, 본문(body)이 없어야 해요.
  • 300 - 399는 리다이렉션(Redirection) 응답이에요.
  • 400 - 499는 클라이언트 오류(Client Error) 응답이에요.
    • 404 "Not Found"가 가장 익숙한 예시죠.
  • 500 - 599는 서버 오류(Server Error) 응답이에요.

여기서 FastAPI가 똑똑하게 처리해 주는 점이 하나 있어요. 204처럼 본문이 없어야 하는 상태 코드를 알면, FastAPI는 OpenAPI 문서에도 "응답 본문 없음"으로 표기해 줘요. 어떤 상태 코드가 본문을 갖지 않는지 신경 쓸 필요 없이, FastAPI가 알아서 문서에 반영해 주는 거죠.

이름 외우는 요령

세 자리 숫자 중 가운데 숫자에 집중해 보세요. 1xx는 정보, 2xx는 성공, 3xx는 리다이렉션, 4xx는 클라이언트 오류, 5xx는 서버 오류. 가운데 숫자가 곧 응답의 큰 분류가 돼요. 그 뒤에 오는 자리수가 구체적인 뜻을 결정하고요.

기본값 바꾸기

여기서는 _경로 동작_마다 고정된 상태 코드를 선언하는 법을 봤어요. 나중에 Advanced User Guide에서는 요청이나 로직에 따라 기본값과 다른 상태 코드를 돌려주는 방법도 다루게 돼요. 지금 단계에서는 "선언된 기본값을 응답에 그대로 쓴다"는 흐름만 확실히 잡아 두면 충분해요.

더 알아보기 (Learn more)