서비스가 커지고 시스템이 복잡해질수록 개발자가 가장 먼저 마주하는 벽은 ‘에러 메시지’입니다. 로그 파일에 찍힌 ERROR_404나 INVALID_INPUT 같은 단순한 코드를 보며 우리는 생각합니다. ‘그래서 정확히 어디가 잘못됐다는 거지?’ 대부분의 초기 프로젝트는 구현의 편의성을 위해 에러 코드를 평면적(Flat)으로 설계합니다. 단순히 고유한 ID와 짧은 설명문을 매칭하는 방식입니다. 하지만 시스템의 규모가 커지면 이 단순함은 곧 재앙이 됩니다.

평면적인 에러 구조의 가장 큰 문제는 ‘맥락(Context)의 부재’입니다. 동일한 INVALID_PARAMETER 코드가 사용자 인증 단계에서 발생했을 때와 결제 요청 단계에서 발생했을 때, 개발자가 취해야 할 조치는 완전히 다릅니다. 하지만 평면적 구조에서는 이 두 상황이 동일한 코드로 처리됩니다. 결국 개발자는 코드를 다시 뜯어보거나, 로그의 스택 트레이스를 끝까지 추적해야만 실제 원인을 파악할 수 있습니다. 이는 단순한 불편함을 넘어 장애 복구 시간(MTTR)을 늘리는 결정적인 요인이 됩니다.

평면적 에러 설계가 초래하는 세 가지 병목 현상

• 디버깅 효율의 급격한 저하: 에러 코드만으로는 문제의 범위를 좁힐 수 없습니다. 네트워크 문제인지, DB 제약 조건 위반인지, 아니면 비즈니스 로직의 오류인지 구분하기 위해 매번 전체 호출 스택을 분석해야 합니다.
• 클라이언트 대응의 한계: 프론트엔드 개발자는 서버가 보내준 단순한 코드를 보고 사용자에게 적절한 안내를 제공하기 어렵습니다. 결국 ‘알 수 없는 오류가 발생했습니다’라는 무책임한 메시지로 타협하게 됩니다.
• 문서화의 지옥: 수백 개의 평면적 에러 코드가 나열된 엑셀 시트는 아무도 읽지 않는 문서가 됩니다. 코드 간의 상관관계가 없기 때문에 새로운 기능을 추가할 때마다 중복된 코드를 만들거나 기존 코드를 오용하게 됩니다.

그렇다면 우리는 어떤 방향으로 나아가야 할까요? 핵심은 에러를 ‘상태’가 아닌 ‘계층’으로 바라보는 것입니다. 에러 코드는 단순히 무엇이 틀렸는지를 알려주는 표식이 아니라, 문제가 발생한 지점과 성격, 그리고 해결 방법을 암시하는 이정표가 되어야 합니다.

맥락을 담은 계층적 에러 설계(Hierarchical Error Design)

효과적인 에러 시스템은 크게 세 가지 레이어로 구성되어야 합니다. 첫째는 도메인 레이어입니다. 이는 시스템의 어느 영역(예: Auth, Payment, Order)에서 문제가 발생했는지를 정의합니다. 둘째는 카테고리 레이어입니다. 해당 영역 내에서 발생한 오류가 일시적인 네트워크 장애인지, 권한 부족인지, 아니면 데이터 무결성 위반인지를 구분합니다. 마지막은 상세 식별자 레이어로, 구체적으로 어떤 필드나 조건이 잘못되었는지를 명시합니다.

예를 들어, 단순한 USER_NOT_FOUND 대신 AUTH-404-001과 같은 구조를 사용하는 것입니다. 여기서 AUTH는 도메인을, 404는 리소스 부재라는 카테고리를, 001은 구체적인 사용자 식별자 오류임을 나타냅니다. 이렇게 설계하면 개발자는 코드의 앞부분만 보고도 즉시 담당 팀을 찾거나 수정해야 할 모듈을 특정할 수 있습니다.

기술적 구현: 구조화된 에러 응답의 표준화

단순한 문자열 응답을 넘어, JSON 구조 자체에 맥락을 담는 것이 중요합니다. 아래는 권장되는 구조화된 에러 응답의 예시입니다.

필드명	설명	예시 값
code	계층적 고유 식별자	PAY-VAL-102
message	개발자를 위한 기술적 설명	Invalid currency code provided
user_message	사용자에게 보여줄 친절한 메시지	지원하지 않는 통화입니다. 다시 확인해주세요.
context	오류 발생 당시의 가변 데이터	{ "received": "XYZ", "supported": ["USD", "KRW"] }
trace_id	분산 추적을 위한 고유 ID	req-abc-12345

이러한 구조의 핵심은 context 필드에 있습니다. 평면적 에러 코드에서는 불가능했던 ‘동적인 정보’를 전달함으로써, 클라이언트는 서버에 다시 요청을 보내지 않고도 사용자에게 정확히 무엇을 수정해야 하는지 알려줄 수 있습니다. 예를 들어, 입력값이 잘못되었다면 어떤 필드가 어떤 제약 조건에 걸렸는지를 context에 담아 보내는 식입니다.

실무 적용 시 고려해야 할 트레이드오프

물론 계층적 설계가 항상 정답은 아닙니다. 도입 전 반드시 고려해야 할 장단점이 존재합니다.

장점으로는 명확한 책임 분리가 가능해진다는 점입니다. 인프라 팀은 SYS-로 시작하는 코드를, 비즈니스 팀은 BIZ-로 시작하는 코드를 관리하며 서로의 영역을 침범하지 않습니다. 또한, 모니터링 도구(Datadog, New Relic 등)에서 에러 코드의 접두사만으로 대시보드를 구성할 수 있어 장애 감지 속도가 비약적으로 향상됩니다.

단점으로는 초기 설계 비용이 증가한다는 점입니다. 모든 에러 상황을 미리 정의하고 계층을 나누는 작업은 상당한 시간이 소요됩니다. 또한, 너무 세분화된 코드는 오히려 관리 포인트를 늘려 ‘코드 번호 찾기’라는 또 다른 피로감을 유발할 수 있습니다. 따라서 처음부터 완벽한 체계를 잡으려 하기보다, 가장 빈번하게 발생하는 도메인부터 점진적으로 확장하는 전략이 필요합니다.

지금 당장 실행할 수 있는 액션 아이템

현재 프로젝트의 에러 처리가 평면적이라 고통받고 있다면, 다음의 단계별 가이드를 따라 개선해 보십시오.

1단계: 에러 인벤토리 작성

현재 시스템에서 사용 중인 모든 에러 코드를 리스트업 하십시오. 그리고 각 코드가 어떤 도메인에 속하는지, 중복된 의미를 가진 코드는 없는지 분류하십시오. 이 과정에서 불필요하게 세분화되었거나 너무 모호한 코드들을 솎아낼 수 있습니다.

2단계: 도메인 기반 접두사(Prefix) 도입

모든 에러 코드 앞에 도메인을 식별할 수 있는 3~4글자의 접두사를 붙이십시오. USER_ERROR를 USR-100으로 바꾸는 작은 변화만으로도 로그 분석의 효율이 달라집니다. 이때 접두사는 팀 내에서 합의된 표준 명명 규칙을 따라야 합니다.

3단계: 에러 응답 객체의 표준화

단순 문자열이나 정수형 코드를 반환하던 API 응답 형식을 위에서 언급한 구조화된 JSON 형태로 변경하십시오. 특히 trace_id를 포함시켜 로그 시스템과 API 응답을 연결하는 고리를 만드십시오. 이는 장애 발생 시 원인 파악 시간을 획기적으로 줄여줍니다.

결국 좋은 에러 설계란 ‘개발자가 질문하지 않게 만드는 설계’입니다. 에러 코드를 보는 순간 어디서, 왜, 어떻게 해결해야 할지가 그려진다면 그것이 바로 성공적인 아키텍처입니다. 평면적인 코드의 안락함에서 벗어나 맥락이 살아있는 계층적 구조로 전환하십시오. 그것이 시스템의 확장성과 팀의 생산성을 동시에 잡는 유일한 길입니다.