비즈니스 앱을 위한 오류 분류: 일관된 UI와 모니터링

실제 비즈니스 앱에서 오류 분류가 해결하는 문제

오류 분류(error taxonomy)는 모든 사람이 같은 방식으로 오류를 명명하고 그룹화하는 공통의 규칙입니다. 각 화면과 API가 저마다 메시지를 만들어내는 대신, 검증(validation)이나 인증(auth) 같은 소수의 카테고리와 사용자와 모니터링에 어떻게 표시할지에 대한 규칙을 정의합니다.

그 구조가 없으면 동일한 문제가 여러 형태로 나타납니다. 필수 필드 누락은 모바일에서는 “잘못된 요청”으로, 웹에서는 “문제가 발생했습니다”로, 로그에서는 스택 트레이스로 보일 수 있습니다. 사용자는 다음에 무엇을 해야 할지 몰라하고, 온콜 팀은 사용자 실수인지 공격인지 서비스 장애인지 추측하느라 시간을 낭비합니다.

목표는 일관성입니다: 같은 유형의 오류는 같은 UI 동작과 같은 경고 동작을 가져야 합니다. 검증 문제는 정확한 필드를 가리켜야 합니다. 권한 문제는 동작을 중단시키고 어떤 접근 권한이 부족한지 설명해야 합니다. 종속성 실패는 안전한 재시도를 제공하고, 모니터링은 올바른 팀에 경고를 보냅니다.

현실적인 예: 영업 담당자가 고객 기록을 만들려는데 결제 서비스가 다운된 상황을 생각해보세요. 앱이 일반적인 500을 반환하면 담당자는 재시도하고 나중에 중복을 만들 수 있습니다. 종속성-실패 카테고리가 명확하면 UI는 서비스가 일시적으로 사용 불가능하다고 알려주고 중복 제출을 방지하며 모니터링은 적절한 팀에 페이지를 보낼 수 있습니다.

이런 정렬은 하나의 백엔드가 여러 클라이언트를 구동할 때 가장 중요합니다. API, 웹 앱, 모바일 앱, 내부 도구가 모두 동일한 카테고리와 코드를 사용하면 장애가 무작위로 느껴지지 않습니다.

간단한 모델: category, code, message, details

카테고리와 코드와 메시지, 세부 정보를 분리하면 분류 유지 관리가 쉬워집니다. HTTP 상태 코드는 여전히 중요하지만 전부가 되어서는 안 됩니다.

Category는 “UI와 모니터링은 어떻게 행동해야 하는가?”에 답합니다. 한 곳에서는 403이 “인증(auth)”을 의미할 수 있고, 나중에 규칙을 추가하면 다른 403은 “정책(policy)”이 될 수 있습니다. 카테고리는 전송 방식이 아니라 동작에 관한 것입니다.

Code는 “정확히 무슨 일이 있었나?”에 답합니다. 코드는 안정적이고 단순해야 합니다. 버튼 이름을 바꾸거나 서비스를 리팩터해도 코드가 바뀌면 안 됩니다. 대시보드, 경고, 지원 스크립트가 이 코드에 의존합니다.

Message는 “사용자에게 무엇을 말할 것인가?”에 답합니다. 메시지의 대상자를 정하세요. 사용자용 메시지는 짧고 친절해야 합니다. 지원용 메시지는 다음 단계 안내를 포함할 수 있습니다. 로그는 더 기술적이어도 됩니다.

Details는 “이 문제를 고치기 위해 무엇이 필요한가?”에 답합니다. UI가 반응할 수 있도록 세부 정보를 구조화하세요. 폼 오류라면 필드 이름일 것이고, 종속성 문제라면 업스트림 서비스 이름과 retry-after 값일 수 있습니다.

여기 많은 팀이 쓰는 간단한 형태가 있습니다:

{
  "category": "validation",
  "code": "CUSTOMER_EMAIL_INVALID",
  "message": "Enter a valid email address.",
  "details": { "field": "email", "rule": "email" }
}

기능이 바뀌더라도 카테고리는 작고 안정적으로 유지하고, 기존 코드를 재사용하기보다 새로운 코드를 추가하세요. 이렇게 하면 UI 동작, 모니터링 추세, 지원 플레이북이 제품 변화에도 신뢰를 유지합니다.

핵심 카테고리: validation, auth, rate limits, dependencies

대부분의 비즈니스 앱은 어디서나 나타나는 네 가지 카테고리로 시작할 수 있습니다. 백엔드, 웹, 모바일 전반에서 이름과 처리를 동일하게 하면 UI가 일관되게 반응하고 모니터링도 읽기 쉬워집니다.

Validation (예상 가능한 오류)

검증 오류는 사용자 입력이나 비즈니스 규칙이 실패했을 때 발생합니다. 필수 필드 누락, 형식 오류, “할인은 20%를 초과할 수 없음” 또는 “주문 합계는 $0보다 커야 함” 같은 규칙입니다. UI는 일반 경고 대신 정확한 필드나 규칙을 강조해야 합니다.

인증 vs 권한 (예상 가능한 오류)

Auth 오류는 보통 두 가지 경우로 나뉩니다: 인증되지 않음(로그인 안 됨, 세션 만료, 토큰 누락)과 권한 없음(로그인은 되어 있으나 권한이 없음). 이를 다르게 처리하세요. 첫 번째 경우에는 “다시 로그인해 주세요”가 맞습니다. 두 번째는 민감한 정보를 드러내지 않으면서도 명확해야 합니다: “송장 승인 권한이 없습니다.” 같은 식으로요.

Rate limits (예상되지만 시간 기반)

레이트 리미트는 “요청이 너무 많습니다. 나중에 다시 시도하세요.”를 의미합니다. 보통 대량 업로드, 바쁜 대시보드, 반복 재시도에서 나타납니다. retry-after 힌트(예: “30초 기다리세요”)를 포함하고, UI가 서버를 계속 두드리지 않고 백오프하도록 하세요.

종속성 실패 (종종 예상 불가)

종속성 실패는 업스트림 서비스, 타임아웃, 장애에서 옵니다: 결제 제공자, 이메일/SMS, 데이터베이스, 내부 서비스 등. 사용자가 해결할 수 없는 문제이므로 UI는 안전한 대체 동작(드래프트로 저장, 나중에 시도, 지원에 연락)을 제공해야 합니다.

핵심 차이는 동작입니다: 예상 가능한 오류는 정상 흐름의 일부로 정밀한 피드백을 받아야 하고, 예상 불가능한 오류는 불안정성을 알리는 신호로 경고, 상관 ID, 신중한 로깅을 트리거해야 합니다.

단계별: 한 번의 워크숍으로 분류 만들기

분류는 기억하기 쉬울 만큼 작아야 하지만, 두 팀이 같은 문제를 같은 방식으로 라벨링할 수 있을 정도로 엄격해야 합니다.

1) 시간 제한을 정하고 소수 선택

6090분 워크숍으로 시작하세요. 가장 자주 보이는 오류(잘못된 입력, 로그인 문제, 요청 과다, 서드파티 장애, 예기치 못한 버그)를 나열한 뒤, 문서를 확인하지 않고도 모두가 소리 내어 말할 수 있는 612개의 카테고리로 합치세요.

2) 안정적인 코드 체계 합의

로그와 티켓에서 읽기 쉬운 네이밍 패턴을 고르세요. 짧게 유지하고 버전 번호를 피하세요. 일단 배포되면 코드는 영구적인 것으로 취급하세요. 흔한 패턴은 카테고리 접두사와 명확한 슬러그를 합친 형태입니다: AUTH_INVALID_TOKEN 또는 DEP_PAYMENT_TIMEOUT 같은 식으로요。

떠나기 전에 모든 오류가 포함해야 할 항목을 결정하세요: category, code, 안전한 메시지, 구조화된 details, 그리고 trace 또는 request ID.

3) category와 code에 대한 규칙 하나 작성

팀은 카테고리가 쓰레기통이 되면 막힙니다. 간단한 규칙이 도움이 됩니다: category는 “UI와 모니터링이 어떻게 반응할까?”, code는 “정확히 무슨 일이었나?”에 답합니다. 두 실패가 다른 UI 동작을 필요로 한다면 같은 카테고리를 공유하면 안 됩니다.

4) 카테고리별 기본 UI 동작 설정

사용자에게 기본적으로 무엇을 보여줄지 결정하세요. Validation은 필드를 강조합니다. 인증은 로그인 화면으로 보내거나 접근 메시지를 보여줍니다. 레이트 리밋은 “X초 후 다시 시도”를 보여줍니다. 종속성 실패는 차분한 재시도 화면을 보여줍니다. 기본이 정해지면 새 기능도 일회용 처리를 만들지 않고 따라갈 수 있습니다.

5) 실제 시나리오로 테스트

회원가입, 결제, 검색, 관리자 수정, 파일 업로드 같은 다섯 가지 일반 흐름을 실행하고 모든 실패를 라벨링하세요. 그룹이 논쟁하면 보통 더 많은 코드를 추가할 게 아니라 한 가지 규칙을 더 명확히 해야 합니다.

검증 오류: 사용자가 조치할 수 있게 만들기

검증은 보통 즉시 보여줘야 하는 오류 유형입니다. 예측 가능해야 하고 사용자가 무엇을 고쳐야 하는지 알려줘야 하며 재시도 루프를 유발하지 않아야 합니다。

필드 수준과 폼 수준 검증은 다른 문제입니다. 필드 수준 오류는 하나의 입력(email, phone, amount)에 대응합니다. 폼 수준 오류는 입력 조합(시작일이 종료일보다 이전이어야 함)이나 전제 조건(배송 방법 미선택)과 관련됩니다. API 응답이 이 차이를 명확히 해야 UI가 올바르게 반응할 수 있습니다。

일반적인 비즈니스 규칙 실패 예는 “신용 한도 초과”입니다. 사용자가 유효한 숫자를 입력했더라도 계정 상태로 인해 허용되지 않을 수 있습니다. 이는 폼 수준 검증 오류로 처리하고 명확한 이유와 안전한 힌트(예: “사용 가능한 한도는 $500입니다. 금액을 줄이거나 한도 상향을 요청하세요.”)를 제공하세요. 데이터베이스 필드명이나 스코어링 모델, 규칙 엔진 단계 같은 내부 이름을 노출하지 마세요。

실행가능한 응답은 보통 안정적인 코드(단순 영어 문장이 아닌), 사용자 친화적 메시지, 필드 수준 문제를 위한 선택적 필드 포인터, 그리고 짧은 안전한 힌트(형식 예시, 허용 범위)를 포함합니다. 엔지니어를 위한 규칙 이름이 필요하면 UI가 아닌 로그에 넣으세요。

검증 실패는 시스템 오류와 다르게 로그하세요. 패턴을 디버그할 수 있을 만큼의 컨텍스트를 남기되 민감한 데이터는 저장하지 마세요. 사용자 ID, 요청 ID, 규칙 이름 또는 코드, 실패한 필드를 기록하세요. 값은 필요한 것(보통 “있음/없음” 또는 길이)만 기록하고 민감한 정보는 마스킹하세요。

UI에서는 재시도보다 수정을 돕는 데 초점을 맞추세요. 필드를 강조하고 사용자가 입력한 값을 유지하며 첫 번째 오류로 스크롤하고 자동 재시도를 비활성화하세요. 검증 오류는 일시적인 것이 아니므로 “다시 시도”는 시간 낭비입니다。

인증 및 권한 오류: 보안성과 명확성 유지

인증과 권한 실패는 사용자에게 비슷하게 보일 수 있지만 보안, UI 흐름, 모니터링 관점에서 다른 의미를 가집니다. 이를 분리하면 웹, 모바일, API 클라이언트 전반에서 동작이 일관됩니다。

인증되지 않음(Unauthenticated)은 앱이 사용자를 증명할 수 없다는 뜻입니다. 보통 자격 증명 누락, 토큰 유효성 실패, 세션 만료가 원인입니다. 금지(Forbidden)는 사용자가 알려져 있지만 해당 동작을 수행할 권한이 없다는 뜻입니다。

세션 만료는 가장 흔한 엣지 케이스입니다. 리프레시 토큰을 지원하면 한 번의 무음 리프레시를 시도한 뒤 원래 요청을 재시도하세요. 리프레시 실패 시에는 인증되지 않음 오류를 반환하고 사용자를 로그인으로 안내하세요. 루프를 피하세요: 한 번의 리프레시 시도 후에는 멈추고 명확한 다음 단계를 노출하세요。

UI 동작은 예측 가능해야 합니다:

• 인증되지 않음: 로그인 유도, 사용자가 하려던 작업을 보존
• 권한 없음: 페이지에 머물며 접근 메시지 표시, “권한 요청” 같은 안전한 동작 제공
• 계정 비활성화 또는 취소: 로그아웃시키고 지원이 도울 수 있다는 짧은 메시지 표시

감사를 위해 누가 무엇을 시도했고 왜 차단되었는지 답할 수 있을 만큼 로그를 남기세요. 유용한 기록에는 사용자 ID(알려진 경우), 테넌트/워크스페이스, 동작 이름, 리소스 식별자, 타임스탬프, 요청 ID, 정책 검사 결과(허용/거부)가 포함됩니다. 토큰과 비밀번호는 로그에 포함하지 마세요。

사용자 메시지에서는 역할 이름, 권한 규칙, 내부 정책 구조를 드러내지 마세요. “송장 승인 권한이 없습니다”는 “Only FinanceAdmin can approve invoices.”보다 안전합니다。

레이트 리밋 오류: 부하 상황에서 예측 가능한 동작

레이트 리밋은 버그가 아닙니다. 안전 장치입니다. 이를 일급 카테고리로 취급해 UI, 로그, 경고가 트래픽 급증 시 일관되게 반응하도록 하세요。

레이트 리밋은 보통 몇 가지 형태로 나타납니다: 사용자별(한 사람이 너무 빠르게 클릭), IP별(사무실 네트워크 뒤 다수의 사용자), API 키별(하나의 통합 작업이 과도하게 실행). 원인은 해결 방법이 다르므로 중요합니다。

좋은 레이트-리밋 응답에 포함되어야 할 것

클라이언트는 두 가지가 필요합니다: 제한되었다는 사실과 언제 다시 시도할 수 있는지. HTTP 429와 명확한 대기 시간(예: Retry-After: 30)을 반환하세요. 또한 대시보드가 사건을 그룹화할 수 있도록 안정적인 오류 코드(예: RATE_LIMITED)를 포함하세요。

메시지는 차분하고 구체적으로 유지하세요. “요청이 너무 많습니다”는 기술적으로 맞지만 도움이 되지 않습니다. “30초 후에 다시 시도하세요”는 기대치를 설정하고 반복 클릭을 줄입니다。

UI 측에서는 빠른 재시도를 막으세요. 간단한 패턴은 대기 시간 동안 동작 버튼을 비활성화하고 짧은 카운트다운을 보여준 뒤 타이머 종료 후 안전한 한 번의 재시도를 제공하는 것입니다. 데이터가 손실되었다고 사용자에게 생각하게 하는 문구는 피하세요。

모니터링에서는 팀이 과잉 반응하는 경우가 많습니다. 모든 429에 사람을 호출하지 마세요. 비정상적인 급증—특정 엔드포인트, 테넌트, API 키에 대한 갑작스러운 증가—에 대해 경고하세요。

백엔드 동작도 예측 가능해야 합니다. 자동 재시도에는 지수 백오프를 사용하고 재시도를 멱등하게 만드세요. “청구서 생성” 같은 동작은 첫 번째 요청이 실제로 성공했을 경우 두 번째 요청이 중복 청구서를 만들지 않아야 합니다。

종속성 실패: 혼란 없이 장애 처리하기

종속성 실패는 사용자가 입력을 잘했음에도 발생하는 오류입니다. 결제 게이트웨이가 타임아웃되거나 데이터베이스 연결이 끊기거나 업스트림 서비스가 5xx를 반환하는 경우입니다. 이를 별도의 카테고리로 취급해 UI와 모니터링이 예측 가능하게 행동하도록 하세요。

먼저 실패의 일반적인 유형을 명명하세요: 타임아웃, 연결 오류(DNS, TLS, 연결 거부), 업스트림 5xx(Bad Gateway, Service Unavailable). 근본 원인을 모를지라도 무엇이 일어났는지 캡처하고 일관되게 응답할 수 있습니다。

재시도 vs 빠른 실패

재시도는 짧은 일시적 문제에 도움이 되지만, 장애를 악화시킬 수도 있습니다. 모든 팀이 같은 판단을 하도록 간단한 규칙을 사용하세요。

• 일시적일 가능성이 높은 오류(타임아웃, 연결 리셋, 502/503)는 재시도
• 종속성의 4xx, 인증 실패, 리소스 없음 같은 사용자 원인 또는 영구적 경우는 빠르게 실패
• 재시도를 제한(예: 2~3회)하고 작은 백오프 추가
• 멱등성이 없는 동작은 idempotency 키 없이는 절대 재시도하지 않음

UI 동작 및 안전한 대체

종속성 실패가 발생하면 사용자가 할 수 있는 다음 단계를 제시하세요: “일시적 문제입니다. 잠시 후 다시 시도하세요.” 안전한 대체가 있다면 제공하세요. 예: Stripe가 다운되면 사용자가 주문을 “결제 대기”로 저장하고 이메일 확인을 보내는 식으로 카트를 잃지 않도록 하세요。

또한 이중 제출을 보호하세요. 느린 응답 중 사용자가 “결제”를 두 번 탭하면 시스템이 이를 감지해야 합니다. 생성 및 청구 흐름에는 멱등성 키를 사용하거나, 다시 실행하기 전에 “이미 결제됨” 같은 상태 검사를 하세요。

모니터링용으로는 다음 질문에 빠르게 답할 수 있는 필드를 기록하세요: “어떤 종속성이 실패했고, 얼마나 심각한가?” 종속성 이름, 엔드포인트/작업, 소요 시간, 최종 결과(타임아웃, 연결, 업스트림 5xx)를 캡처하세요. 그러면 경고와 대시보드가 의미 있고 시끄럽지 않게 됩니다。

채널 전반에서 모니터링과 UI 일관성 만들기

분류는 모든 채널이 같은 언어를 쓸 때만 작동합니다: API, 웹 UI, 모바일 앱, 로그. 그렇지 않으면 같은 문제가 다섯 가지 다른 메시지로 나타나고, 누가 사용자 실수인지 서비스 장애인지 알기 어렵습니다。

HTTP 상태 코드는 보조 레이어로 취급하세요. 프록시와 기본 클라이언트 동작에 도움을 주지만, 의미는 category와 code가 담아야 합니다. 종속성 타임아웃은 여전히 503일 수 있지만, 카테고리는 UI에 “다시 시도”를 제안하고 모니터링에는 온콜을 호출하도록 지시합니다。

모든 API가 동일한 표준 오류 형태를 반환하게 하세요, 소스가 데이터베이스이든 인증 모듈이든 서드파티 API든 상관없이. 이런 단순한 형태는 UI 처리와 대시보드를 일관되게 유지합니다:

{
  "category": "dependency",
  "code": "PAYMENTS_TIMEOUT",
  "message": "Payment service is not responding.",
  "details": {"provider": "stripe"},
  "correlation_id": "9f2c2c3a-6a2b-4a0a-9e9d-0b0c0c8b2b10"
}

Correlation ID는 “사용자가 오류를 보았음”과 “우리가 추적할 수 있음” 사이의 다리입니다. UI에 correlation_id를 표시하세요(복사 버튼이 도움이 됨) 그리고 백엔드에는 항상 로깅해 한 요청을 서비스 전반에서 추적할 수 있도록 하세요。

UI에 보여줄 것과 로그에만 남길 것을 합의하세요. 실용적인 분배는: UI에는 category, 명확한 메시지, 다음 단계; 로그에는 기술적 오류 세부와 요청 컨텍스트; 둘 다 correlation_id와 안정적인 오류 코드를 공유합니다。

일관된 오류 시스템을 위한 빠른 체크리스트

일관성은 가장 좋은 의미에서 지루합니다: 모든 채널이 같은 동작을 하고 모니터링은 진실을 말합니다。

백엔드(백그라운드 작업과 웹후크 포함)를 먼저 확인하세요. 필드가 선택적이면 사람들은 건너뛰고 일관성이 깨집니다。

• 모든 오류에 category, 안정적인 code, 사용자 안전 메시지, trace ID가 포함되어야 합니다.
• 검증 문제는 예상 가능한 문제이므로 페이징 알림을 트리거하지 않습니다.
• 인증 및 권한 문제는 보안 패턴을 위해 추적되지만 장애로 취급되지 않습니다.
• 레이트 리밋 응답에는 재시도 힌트(예: 대기 시간(초))가 포함되고 경고를 스팸하지 않습니다.
• 종속성 실패에는 종속성 이름과 타임아웃 또는 상태 세부 정보가 포함됩니다。

그다음 UI 규칙을 확인하세요. 각 카테고리는 사용자가 다음에 무엇을 해야 할지 추측하지 않도록 하나의 예측 가능한 화면 동작에 매핑되어야 합니다: 검증은 필드 강조, 인증은 로그인 유도 또는 접근 표시, 레이트 리밋은 차분한 대기, 종속성 실패는 재시도와 가능한 대체 제공。

간단한 테스트는 스테이징에서 각 카테고리의 오류를 하나씩 트리거해 웹 앱, 모바일 앱, 관리자 패널에서 동일한 결과가 나오는지 확인하는 것입니다。

흔한 실수와 실용적 다음 단계

오류 시스템을 망가뜨리는 가장 빠른 방법은 그것을 뒷전으로 여기는 것입니다. 서로 다른 팀이 같은 문제에 대해 다른 단어, 다른 코드, 다른 UI 동작을 사용하게 됩니다. 분류 작업은 일관성을 유지할 때 가치가 있습니다。

흔한 실패 패턴:

• 내부 예외 텍스트를 사용자에게 노출. 혼란을 주고 민감한 정보를 드러낼 수 있음.
• 모든 4xx를 “검증(validation)”으로 라벨링. 권한 부족은 필드 누락과 같지 않음.
• 기능별로 새 코드를 아무 검토 없이 발명. 결국 같은 5가지 의미를 가진 200개의 코드가 생김.
• 잘못된 실패를 재시도. 권한 오류나 잘못된 이메일 주소를 재시도하면 소음만 늘어남。

간단한 예: 영업 담당자가 “고객 생성” 폼을 제출했는데 403을 받는 상황을 생각하세요. UI가 모든 4xx를 검증으로 처리하면 임의의 필드를 강조하고 “입력을 수정하세요”라고 하여 실제 문제(역할)가 무엇인지 알려주지 않습니다. 모니터링은 검증 문제의 급증을 보이지만 실제 문제는 역할입니다。

한 번의 짧은 워크숍에 맞는 실용적 다음 단계: 한 페이지짜리 분류 문서 작성(카테고리, 사용 시기, 5~10개의 대표 코드), 메시지 규칙 정의(사용자에게 보이는 것과 로그에 남기는 것), 새 코드에 대한 가벼운 검토 게이트 추가, 카테고리별 재시도 규칙 설정, 끝까지 구현(백엔드 응답, UI 매핑, 모니터링 대시보드).

AppMaster (appmaster.io)로 빌드하는 경우, 이러한 규칙을 한 곳에 중앙화하면 백엔드, 웹 앱, 네이티브 모바일 앱 전반에 동일한 카테고리와 코드 동작을 유지하는 데 도움이 됩니다.