FastAPI 오류 해결 기록

422 Unprocessable Entity가 계속 뜰 때

증상: 요청 body를 보냈는데 계속 422 에러가 반환됨.

원인: Pydantic 모델의 필드 타입과 실제 전송한 JSON 타입 불일치. 특히 int 필드에 문자열 숫자를 보내거나, 필수 필드 누락이 흔한 원인이었습니다.

해결: 응답 body의 detail 배열을 읽으면 어떤 필드가 왜 실패했는지 정확히 나옵니다. 에러 메시지를 먼저 읽는 습관이 중요합니다.

{
  "detail": [
    { "loc": ["body", "price"], "msg": "Input should be a valid integer" }
  ]
}

Path 파라미터와 쿼리 파라미터 혼동

증상: /items/{item_id} 엔드포인트가 의도대로 동작하지 않음.

원인: 함수 시그니처에서 경로에 없는 파라미터는 자동으로 쿼리 파라미터가 되는 규칙을 모르고 있었습니다.

해결: 경로에 선언한 이름과 함수 인자 이름을 정확히 일치시키고, 나머지는 쿼리 파라미터로 문서(/docs)에서 확인.

uvicorn 재시작 없이 코드가 반영 안 될 때

증상: 코드를 수정했는데 API 응답이 그대로.

해결: 개발 중에는 uvicorn main:app --reload로 실행해 파일 변경 시 자동 재시작되게 합니다. 운영 환경에서는 --reload를 빼야 합니다.

정리

• 에러 응답 body에 원인이 대부분 적혀 있다 — 추측 전에 읽기
• FastAPI의 자동 문서(/docs)는 디버깅 도구로도 유용하다
• 개발/운영 실행 옵션을 구분해서 기록해두기