1. 들어가며
사이드 프로젝트를 진행하며 궁금한 점이 생겼다. API에서 에러가 발생하면 어떤 상태 코드를 보내야 할까?
프로젝트 팀원들과 이야기할 때마다 의견이 갈렸다. RESTful 원칙에 따라 400번대, 500번대를 사용하자는 의견과 응답을 정상적으로 받았으니 200이 맞다는 의견이 있었다.
나는 여기서 200이 맞다고 생각했다. 에러를 반환했다는 것 자체가 HTTP 통신에는 성공한 것이고, HTTP는 RFC로 정의된 표준 프로토콜인데 굳이 왜 변경해야 하는지 의문이었다. 차라리 그럴 거면 커스텀 상태코드를 만들어서 사용하는 게 낫지 않을까 생각했다.
ZeroCho님의 유튜브 영상을 보고 다시 고민이 떠올라 이번 기회에 찾아보게 되었다. 클라이언트와 서버 입장에서 각각의 논리가 다 이해되었고, 상황과 서비스에 따라서 트레이드오프를 해야 한다는 걸 깨달았다.
또한 혹시나 해서 적는건데 절대 싸우자는 의미가 아니다 !! 결론은 각자 서비스에 맞는 스타일을 쓰자. 정답은 없다.
2. HTTP 상태코드의 원칙과 현실
REST 아키텍처에서는 HTTP 상태코드를 명확하게 구분해서 사용하라고 한다. 200은 성공, 400번대는 클라이언트 오류, 500번대는 서버 오류로 말이다. 로그인 실패라면 401, 잘못된 요청이면 400을 보내는 게 원칙이다. 이론적으로는 깔끔하다. API 문서만 봐도 어떤 에러가 나올지 예측할 수 있고, 프론트엔드에서도 상태코드만 보고 처리 방향을 정할 수 있다.
하지만 실무에서는 문제가 생긴다. 4xx, 5xx 코드가 나올 때마다 모니터링 시스템에서 알람이 울린다면, 운영팀에서는 진짜 서버 장애와 단순 비즈니스 로직 실패를 구분하기 어렵다. 대표적으로 404가 있다. GET /users/123에서 404가 나왔을 때, API 엔드포인트가 없는 걸까? 아니면 API는 있지만 해당 사용자가 없는 건지 클라이언트는 구분하기 어렵다.
3. 200 vs RESTful 방식, 어떤 게 더 좋을까?
이제 두 방식의 장단점을 구체적으로 살펴보자. AI 툴과 구글링을 통해 알아보고 각 접근법의 장단점을 정리해보았다.
- 200 + body 에러 방식
장점으로는 개발 편의성이 크다. 모든 API가 동일한 응답 구조를 가지니까 프론트엔드에서 일관된 에러 처리 패턴을 사용할 수 있다.
단점은 HTTP 표준을 무시한다는 점이다. 브라우저나 CDN이 잘못된 응답도 성공으로 캐시할 수 있고, 히스토리를 모르는 개발자가 코드를 본다면 혼란스러워할 수 있다. 또한 웹서버 로그만으로는 실제 성공률을 파악하기 어렵다.
- RESTful 방식
장점은 HTTP 표준에 부합한다는 점이다. 브라우저, 프록시, 각종 도구들이 상태코드를 보고 적절히 처리할 수 있다. API 문서도 명확해진다. "로그인 실패 시 401 반환"이라고 쓰면 모든 개발자가 이해하므로 유지보수가 용이하다. 웹서버 로그만 봐도 대략적인 성공/실패 비율을 알 수 있어 운영에 도움이 된다.
단점은 운영 복잡성이다. 정상적인 비즈니스 실패(로그인 실패, 권한 없음)와 실제 서버 장애를 구분해야 한다. 프론트엔드에서도 HTTP 레벨 에러와 비즈니스 로직 에러를 따로 처리해야 해서 코드가 복잡해진다.
- 실제 성능/운영 임팩트 비교
성능 면에서는 큰 차이가 없다. 둘 다 같은 HTTP 요청/응답이고, 상태코드 몇 자리 숫자 차이일 뿐이다.
결국 팀의 상황과 우선순위에 따라 선택해야 한다. 빠른 개발과 운영 단순성을 원한다면 200 방식이, HTTP 표준 준수와 명확성을 원한다면 RESTful 방식이 적합하다.
4. 마무리
이걸로 나의 결과를 통해 단정 짓기에는 무리가 있는 것 같다. 많은 프로젝트가 있고 많은 개인 사정들이 있을 것이다. 그걸 내가 이게 맞다고 글을 적기엔 어려운 부분이 많다. 그래서 다들 정답이 없나 보다. 다들 자신의 프로젝트에서 잘 쓰고 있을 것이고, 나처럼 고민하는 분에게는 이러한 이유 때문에 정답이 없구나 생각해 주시면 좋을 것 같다.
이번에 조사하면서 내 생각도 조금 바뀌었다. 처음엔 "HTTP 통신 성공했으니 200이 맞다"고 생각했는데, 사소한 프로젝트라도 규약을 지켜가며 쌓아가야 되지 않을까? 라는 생각이 들게 되었다. 앞으로는 프로젝트 초기에 팀과 상황을 고려해서 방식을 정하고, "왜 이 방식을 선택했는지" 명확한 근거를 가지고 결정하는 게 중요할 것 같다.