<aside> 🚨 에러 분류 · CrawlerError boundary · 재시도 / 회로 차단 · 구조화 로깅 · Prometheus 메트릭 · 알림 / 인시던트 대응 · 원본: .claude/rules/04-error-handling.md

</aside>

핵심 원칙

• Fail Gracefully — production 코드에서 panic 금지. recover 는 top-level handler 한정.
• Error Context — fmt.Errorf 의 %w 로 wrap, 식별 정보 (URL · article ID · source) 포함, error chain 보존.
• Error Types — 카테고리 별 custom 타입으로 type-based 분기 + 기계 판독 코드.

Layer Rules — CrawlerError vs fmt.Errorf

처음부터 모든 에러를 구조화하지 않고, layer 별로 분리:

MUST — CrawlerError 로 반환 (boundary)

• internal/processor/fetcher/ 의 fetch/parse 결과 (Network / RateLimit / Timeout / Parse / NotFound / Forbidden)
• internal/processor/validate/ 의 검증 결과 (Validation, 코드 VAL_001 ~ VAL_006)
• internal/storage/service/ 의 boundary 메소드 (Storage, STORAGE_001~003)
• 카테고리화된 DB 에러 (Database, DB_001~004)

MAY — fmt.Errorf 유지가 적절

• pkg/ 의 generic 유틸 (pkg/queue · pkg/links · pkg/redis · pkg/config) — 도메인 의존성 갖지 않음
• internal/ 의 비-노출 helper 함수
• internal/classifier · publisher 의 비-boundary 경로

Error Category

// 일시적 — 재시도 가능
ErrCategoryNetwork    "network"
ErrCategoryRateLimit  "rate_limit"
ErrCategoryTimeout    "timeout"

// 영구 — 재시도 무의미
ErrCategoryNotFound   "not_found"
ErrCategoryForbidden  "forbidden"
ErrCategoryParse      "parse"
ErrCategoryValidation "validation"

// 시스템
ErrCategoryDatabase   "database"
ErrCategoryQueue      "queue"
ErrCategoryStorage    "storage"

// 로직
ErrCategoryConfig     "config"
ErrCategoryInternal   "internal"

Error Code 규약

NET_001  Connection refused
NET_002  Connection timeout
NET_003  DNS resolution failed

HTTP_400 / 403 / 404 / 429 / 500 / 503

PARSE_001 Invalid HTML structure
PARSE_002 Missing required selector
PARSE_003 Encoding error
PARSE_004 Invalid JSON

VAL_001~005  Missing field / Invalid format / Too short / Too long / Quality threshold
DB_001~004   Connection / Query timeout / Constraint / Deadlock
QUEUE_001~003  Publish / Full / Malformed
EMB_001~003    API rate limited / Token limit / Model error