API 개발하다 보면 오류 처리를 어디까지 세분화해야 할지 고민되지 않으셨나요? HTTP 상태 코드만 쓰면 되는 줄 알았는데, 막상 실무에서 400 에러만 계속 보면서 "도대체 뭐가 문젠데?"라고 되물었던 기억이 납니다. 그래서 내부 오류 코드 체계를 도입했는데, 디버깅은 확실히 빨라졌지만 관리해야 할 것도 덩달아 늘어나더군요. 과연 이게 효율일까요, 아니면 또 다른 짐일까요?
디버깅, 정말 빨라지는가
오류 코드 체계를 제대로 갖춰놓으면 문제 원인을 찾는 속도가 확연히 달라집니다. 예전에 제가 참여했던 프로젝트에서는 API 응답이 그냥 "Bad Request"만 던져줬거든요. 클라이언트 개발자가 매번 서버 로그 봐달라고 요청했고, 저는 로그 뒤져가며 "아, 이건 파라미터 누락이네요" 하고 답변하는 게 일상이었습니다. 그러다 HTTP 상태 코드와 함께 내부 코드를 붙이는 구조로 바꿨습니다. 인증 실패는 AUTH_001, 권한 부족은 AUTH_002, 필수 파라미터 누락은 VAL_001 이런 식으로요.
바꾸고 나니 확실히 디버깅 시간이 줄었습니다. 클라이언트 쪽에서 오류 코드만 보고 "아, 토큰 만료구나" 하고 바로 재시도 로직을 태우더군요. 서버 쪽에서도 모니터링 대시보드에 오류 코드별 발생 빈도를 집계해놨더니, 어떤 종류의 에러가 많이 터지는지 한눈에 보였습니다. 특히 운영 환경에서 장애 대응할 때 이게 빛을 발했어요. 예를 들어 VAL_003(잘못된 날짜 형식) 에러가 갑자기 급증하면 "클라이언트 배포 후 날짜 포맷이 바뀌었구나" 하고 즉시 원인 추정이 가능했습니다.
다만 여기서 중요한 건, 오류 코드가 실제로 문제를 구분해줄 만큼 구체적이어야 한다는 점입니다. 막연하게 ERR_001, ERR_002 이렇게만 만들어놓으면 결국 문서 보러 가야 하고, 그럼 차라리 명확한 메시지를 주는 게 나을 수 있습니다. 저는 코드에 의미를 담는 네이밍 규칙을 정했습니다. AUTH(인증), PERM(권한), VAL(검증), DB(데이터베이스) 같은 접두사를 붙여서 카테고리를 구분하고, 뒤에 세부 번호를 붙이는 식이었죠. 이렇게 하니 코드만 봐도 대략적인 문제 영역이 감이 왔습니다.
설계 부담, 생각보다 크다
그런데 솔직히 말하면, 오류 코드 체계를 제대로 만들려면 초기 설계 비용이 만만치 않습니다. 처음엔 "그냥 몇 개 정의하면 되겠지" 싶었는데, 막상 하다 보니 고민할 게 한두 가지가 아니더군요. 일단 어떤 기준으로 코드를 나눌지부터 정해야 합니다. HTTP 상태 코드와의 관계는 어떻게 설정할지, 코드 번호 체계는 어떻게 가져갈지, 같은 오류라도 발생 맥락에 따라 다른 코드를 줄지 말지 등등.
더 큰 문제는 유지보수입니다. 새 기능을 추가할 때마다 새로운 오류 케이스가 생기고, 그때마다 코드를 정의해야 합니다. 그러다 보면 코드가 계속 늘어나고, 어느 순간 "이 코드는 언제 쓰는 거였더라?" 하고 헷갈리는 상황이 옵니다. 제가 경험한 프로젝트에서는 오류 코드가 200개를 넘어가면서 관리가 어려워지기 시작했습니다. 같은 의미인데 다른 코드가 중복으로 생기기도 하고, 더 이상 쓰지 않는 레거시 코드가 문서에만 남아있기도 했죠.
그래서 오류 코드 추가를 아무나 할 수 없도록 정책을 만들었습니다. 새 코드를 만들기 전에 기존 코드 중에 재사용 가능한 게 없는지 먼저 확인하고, 정말 필요한 경우에만 API 설계 담당자의 승인을 받아 추가하도록 했습니다. 또한 분기마다 사용하지 않는 코드를 정리하는 시간을 따로 잡았습니다. 이런 프로세스 없이는 오류 코드 체계가 오히려 혼란의 원인이 될 수 있습니다.
- 오류 코드는 HTTP 상태 코드와 함께 사용하되, 상태 코드만으로 설명 안 되는 세부 상황에만 추가합니다.
- 코드 네이밍은 접두사(카테고리) + 번호 조합으로 통일하고, 팀 전체가 같은 규칙을 따르도록 문서화합니다.
- 신규 코드 추가 시 설계 검토를 거치고, 정기적으로 미사용 코드를 정리하는 프로세스를 마련합니다.
- 오류 코드와 메시지, 발생 조건을 명시한 문서를 항상 최신 상태로 유지합니다.
관리 전략, 실전에서 어떻게 적용할까
오류 코드 체계가 효과를 발휘하려면 단순히 코드만 만들어놓는 게 아니라, 어떻게 관리하고 활용할지에 대한 전략이 필요합니다. 같은 서비스 안에서도 A API는 오류 코드를 상세하게 주고, B API는 그냥 메시지만 던지면 클라이언트 입장에서 혼란스럽습니다. 그래서 프로젝트 초반에 오류 응답 포맷을 명확히 정의했습니다. 모든 API가 동일한 JSON 구조를 사용하도록 하고, 여기에 HTTP 상태 코드, 내부 오류 코드, 사람이 읽을 수 있는 메시지, 그리고 필요시 추가 정보를 담는 필드를 포함시켰습니다.
문서화도 빼놓을 수 없습니다. 아무리 잘 만든 오류 코드라도 개발자가 그 의미를 모르면 소용없습니다. API 문서에 오류 코드 전용 섹션을 만들어서, 각 코드가 어떤 상황에서 발생하는지, 클라이언트는 어떻게 대응해야 하는지를 설명해뒀습니다. 예를 들어 AUTH_001(토큰 만료)의 경우 "리프레시 토큰으로 새 액세스 토큰을 발급받으세요"라는 가이드를 함께 제공했죠. 이렇게 하니 클라이언트 개발자가 문의하는 횟수가 확실히 줄었습니다.
모니터링 관점에서도 오류 코드는 유용합니다. 서버 로그에 오류 코드를 함께 남기고, 이를 집계해서 대시보드에 띄웠습니다. 어떤 코드가 얼마나 자주 발생하는지, 특정 시간대에 특정 오류가 급증하지는 않는지를 실시간으로 확인할 수 있었습니다. 한 번은 VAL_005(잘못된 이메일 형식) 에러가 평소보다 10배 이상 늘어난 적이 있었는데, 알고 보니 클라이언트 앱에서 이메일 입력 필드 유효성 검사가 빠진 버전이 배포된 거였습니다. 오류 코드 모니터링 덕분에 빠르게 문제를 인지하고 대응할 수 있었습니다.
국내 정보통신산업진흥원(NIPA) 자료에 따르면 API 설계 시 명확한 오류 처리 체계를 갖춘 경우 개발 및 운영 비용이 평균 20~30% 절감된다고 합니다(출처: 정보통신산업진흥원). 물론 이건 통계일 뿐이고, 프로젝트 규모와 팀 상황에 따라 달라집니다. 중요한 건, 오류 코드 체계를 도입했다면 그에 맞는 관리 프로세스도 함께 마련해야 효과를 본다는 점입니다.
결국 API 오류 코드 체계는 디버깅 효율과 설계 부담이라는 두 마리 토끼를 동시에 안고 갑니다. 규모가 작은 프로젝트나 초기 단계에서는 굳이 복잡한 코드 체계를 만들 필요 없습니다. HTTP 상태 코드와 명확한 메시지만으로도 충분할 때가 많죠. 하지만 서비스가 커지고 API 개수가 늘어나면, 체계적인 오류 코드가 장기적으로 훨씬 큰 이득을 가져다줍니다. 다만 그 체계를 유지하려면 문서화, 모니터링, 정기 리뷰 같은 관리 노력을 아끼지 말아야 합니다. 여러분 프로젝트는 지금 어느 단계인가요? 한 번쯤 점검해보시길 권합니다.
댓글
댓글 쓰기