---
id: pattern-error-handling
title: "Error Handling Pattern"
category: "Pattern_CrossCutting"
status: "draft"
verification_status: "applied"
canonical_id: ""
aliases: ["error handling", "오류 처리 패턴", "graceful degradation", "result type", "retry", "fallback"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.89
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["pattern", "cross-cutting", "error-handling", "resilience", "platform-independent"]
raw_sources: ["일반 소프트웨어 공학 지식", "ConnectAI/src/core/* (적용 예)"]
applied_in: ["ConnectAI"]
github_commit: ""
---

# [[Error Handling Pattern]]

## 🎯 한 줄 통찰 (One-line insight)
견고한 오류 처리는 "**실패를 분류하고(복구 가능/불가), 흔한 실패는 결과값으로·예외는 진짜 예외에, 부가 작업 실패는 본류를 막지 않게, 사용자에겐 행동 지침으로 번역**" 하는 것이다.

## 🧠 핵심 개념 (Core concepts)
1. **분류:** 복구 가능(재시도/폴백) vs 불가(즉시 실패) vs 부가(무시).
2. **결과 타입 vs 예외:** 흔한 실패는 `{ok,error}` 유니온, 계약 위반은 throw.
3. **재시도/폴백:** 일시 오류는 backoff 재시도, 대안 경로 폴백.
4. **graceful degradation:** 핵심은 살리고 부가만 끈다(이유 주석 필수).
5. **사용자 번역:** 기술 에러→무엇을 하면 되는지.

## 📖 세부 내용 (Details · 패턴 명세)
- **Problem (언제 쓰나):** I/O·네트워크·외부 의존이 있는 모든 코드.
- **사용 조건:** 실패 유형을 구분 가능; 복구/대안 전략 존재.
- **장점:** 복원력, 디버깅 용이, UX 개선, 부분 장애 격리.
- **단점:** 코드량↑, 잘못된 삼킴은 버그 은폐.
- **대안:** 크래시-온리(빠른 실패+재시작), 서킷 브레이커(연속 실패 차단).
- **실패 사례:** 무음 빈 catch 로 실패 은폐; `||` 로 0/'' 삼킴; 무한 재시도; 사용자에게 raw 스택 노출; 부가 실패가 본류 중단.

## 💻 코드 패턴 (Code patterns)
```text
result = op() -> { ok:true, val } | { ok:false, error }   # 흔한 실패는 유니온
for engine in engines: try { return call(engine) } catch { last=e }  # 폴백
try { sideEffect() } catch { /* 부가 — 본류 안 막음(이유 주석) */ }
showUser(translate(error))                                 # 행동 지침으로 번역
catch (e) { err = e instanceof Error ? e : new Error(String(e)) }  # 정규화
```
적용 예: [[에러 처리와 커스텀 에러]](G1Error 계층, ErrorTranslator, 보상 트랜잭션), [[LLM 프로바이더 추상화]](엔진 폴백).

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
"모든 에러를 잡아라" 와 "빠르게 실패하라" 의 균형 — 복구 불가·계약 위반은 던지고, 일시·부가만 흡수. 빈 catch 는 *부가 작업 + 이유 주석* 일 때만.

## 🛠️ 적용 사례 (Applied in summary)
ConnectAI errors/errorHandler/transaction/services.

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[패턴 카탈로그 인덱스]]
- **관련 개념:** [[Async Concurrency Pattern]], [[API Client Pattern]], [[소프트웨어 실패 라이브러리]], [[안티패턴 카탈로그]]
- **참조 맥락:** 작은 모델이 어떤 플랫폼이든 실패 경로를 작성할 때 1차 원리.

## 📚 출처 (Sources)
- [S1] 일반 오류 처리/복원력 지식
- [S2] ConnectAI/src/core/errors.ts, errorHandler.ts, transaction.ts, services.ts — 적용 예

## 📝 변경 이력 (Change history)
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
