# Registry: Error Codes # Schema owner: feature-contract-registry-governance # Category enum owner: feature-operational-error-observability-foundation # Last updated: 2026-11-06 # 범위: 저장소 전체 OperationalError의 정본. 제품·fork의 ApiErrorCode enum은 자기 레지스트리·계약을 가진다. # # 행마다의 칸: # code: UPPER_SNAKE_CASE # category: VALIDATION | AUTH | AUTHZ | NOT_FOUND | CONFLICT | # RATE_LIMIT | TRANSIENT_DEPENDENCY | PERMANENT_DEPENDENCY | # DATA_INTEGRITY | INTERNAL # http_status: int (비동기에서만 나는 실패는 자리표시로 500) # retryable: bool # retry_after_seconds: int | null (RATE_LIMIT/TRANSIENT 권고 backoff) # owner_layer: presentation | application | domain | infrastructure | crosscut # client_safe_message: = shared-contract ClientErrorMessages.of(category) — category별 한국어 문구 표 # 하나(소유자 결정 11). 토큰·principal 원문·내부 경로·stack trace를 담지 않는다 # runbook_link: runbook://area/scenario 또는 null (client-error만 null 허용) # compatibility_impact: none | additive | behavior-change | breaking # required_test: 이 행을 지키는 계약 테스트 식별자 # # runbook 규칙 (operational-runbook-contract L80): # retryable=false + category ∈ {AUTH, AUTHZ, RATE_LIMIT, INTERNAL, # TRANSIENT_DEPENDENCY, PERMANENT_DEPENDENCY} ⇒ runbook_link 필수. # VALIDATION/NOT_FOUND/CONFLICT/DATA_INTEGRITY는 client-error로 runbook 면제 가능. # retryable=true 인 모든 row는 runbook_link 필수. # # 로그 레벨은 행의 칸이 아니다. 레벨은 오류 코드가 아니라 실패의 종류와 경로가 정한다. # shared-contract ServerFailureLog — 모든 전송이 쓴다. 영속성·의존성 carrier와 5xx carrier는 ERROR, # 4xx carrier는 남기지 않는다. IllegalArgumentException(BAD_PARAMETER)은 WARN. # web AuthErrorResponseWriter — 보안 필터. 5xx는 ERROR, 4xx는 WARN. # 행에 log_level을 두면 OperationalErrorRegistryContractTest가 실패한다. # 결정: docs/design/2026-11-06-error-code-log-level-design.md 7·10절. errors: # ============================================================ # AUTH (feature-security-operational-baseline / Decision Matrix) # ============================================================ # source: feature-security-operational-baseline L82 — "token 누락 | 401 | AUTH_TOKEN_MISSING | AUTH" - code: AUTH_TOKEN_MISSING category: AUTH http_status: 401 retryable: false retry_after_seconds: null owner_branch: feature-security-operational-baseline owner_layer: presentation client_safe_message: "인증이 필요합니다." runbook_link: "runbook://auth/token-missing" compatibility_impact: none required_test: contract-verification:auth-category # source: feature-security-operational-baseline L83 — "token malformed (parse fail) | 401 | AUTH_TOKEN_MALFORMED | AUTH" - code: AUTH_TOKEN_MALFORMED category: AUTH http_status: 401 retryable: false retry_after_seconds: null owner_branch: feature-security-operational-baseline owner_layer: presentation client_safe_message: "인증이 필요합니다." runbook_link: "runbook://auth/token-malformed" compatibility_impact: none required_test: contract-verification:auth-category # source: feature-security-operational-baseline L84 — "token expired (clock skew tolerance 60s 초과) | 401 | AUTH_TOKEN_EXPIRED | AUTH" - code: AUTH_TOKEN_EXPIRED category: AUTH http_status: 401 retryable: false retry_after_seconds: null owner_branch: feature-security-operational-baseline owner_layer: presentation client_safe_message: "인증이 필요합니다." runbook_link: "runbook://auth/token-expired" compatibility_impact: none required_test: contract-verification:auth-category # source: feature-security-operational-baseline L85 — "invalid signature | 401 | AUTH_TOKEN_INVALID_SIGNATURE | AUTH" - code: AUTH_TOKEN_INVALID_SIGNATURE category: AUTH http_status: 401 retryable: false retry_after_seconds: null owner_branch: feature-security-operational-baseline owner_layer: presentation client_safe_message: "인증이 필요합니다." runbook_link: "runbook://auth/token-invalid-signature" compatibility_impact: none required_test: contract-verification:auth-category # source: feature-security-operational-baseline L86 — "issuer mismatch | 401 | AUTH_ISSUER_MISMATCH | AUTH" - code: AUTH_ISSUER_MISMATCH category: AUTH http_status: 401 retryable: false retry_after_seconds: null owner_branch: feature-security-operational-baseline owner_layer: presentation client_safe_message: "인증이 필요합니다." runbook_link: "runbook://auth/issuer-mismatch" compatibility_impact: none required_test: contract-verification:auth-category # source: feature-security-operational-baseline L87 — "audience mismatch | 401 | AUTH_AUDIENCE_MISMATCH | AUTH" - code: AUTH_AUDIENCE_MISMATCH category: AUTH http_status: 401 retryable: false retry_after_seconds: null owner_branch: feature-security-operational-baseline owner_layer: presentation client_safe_message: "인증이 필요합니다." runbook_link: "runbook://auth/audience-mismatch" compatibility_impact: none required_test: contract-verification:auth-category # source: feature-security-operational-baseline L88 — "unknown kid (JWKS 미캐시) | 401 + Retry-After 5s | AUTH_KID_UNKNOWN | AUTH" - code: AUTH_KID_UNKNOWN category: AUTH http_status: 401 # 2026-06-01: false→true. JWKS rotation 중 unknown kid는 refresh 후 해소 가능한 transient failure. retryable: true retry_after_seconds: 5 owner_branch: feature-security-operational-baseline owner_layer: presentation client_safe_message: "인증이 필요합니다." runbook_link: "runbook://auth/kid-unknown" compatibility_impact: none required_test: contract-verification:auth-category # source: feature-security-operational-baseline L89 — "JWKS endpoint outage ... | AUTH_JWKS_UNAVAILABLE | TRANSIENT_DEPENDENCY" - code: AUTH_JWKS_UNAVAILABLE category: TRANSIENT_DEPENDENCY http_status: 503 retryable: true retry_after_seconds: 30 owner_branch: feature-security-operational-baseline owner_layer: infrastructure client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://auth/jwks-unavailable" compatibility_impact: none required_test: contract-verification:auth-category # source: feature-security-operational-baseline L90 — "claim mapping failure ... | 401 | AUTH_CLAIM_MAPPING_FAILED | AUTH" - code: AUTH_CLAIM_MAPPING_FAILED category: AUTH http_status: 401 retryable: false retry_after_seconds: null owner_branch: feature-security-operational-baseline owner_layer: presentation client_safe_message: "인증이 필요합니다." runbook_link: "runbook://auth/claim-mapping-failed" compatibility_impact: none required_test: contract-verification:auth-category # ============================================================ # AUTHZ (feature-security-operational-baseline) # ============================================================ # source: feature-security-operational-baseline L91 — "valid token + 권한 부족 | 403 | AUTHZ_INSUFFICIENT_PERMISSION | AUTHZ" - code: AUTHZ_INSUFFICIENT_PERMISSION category: AUTHZ http_status: 403 retryable: false retry_after_seconds: null owner_branch: feature-security-operational-baseline owner_layer: presentation client_safe_message: "이 작업을 수행할 권한이 없습니다." runbook_link: "runbook://authz/insufficient-permission" compatibility_impact: none required_test: contract-verification:authz-category # source: feature-security-operational-baseline L92 — "valid token + tenant cross-access | 403 | AUTHZ_TENANT_MISMATCH | AUTHZ" - code: AUTHZ_TENANT_MISMATCH category: AUTHZ http_status: 403 retryable: false retry_after_seconds: null owner_branch: feature-security-operational-baseline owner_layer: presentation client_safe_message: "이 작업을 수행할 권한이 없습니다." runbook_link: "runbook://authz/tenant-mismatch" compatibility_impact: none required_test: contract-verification:authz-category # ============================================================ # INTERNAL (feature-security-operational-baseline + container-runtime) # ============================================================ # source: feature-security-operational-baseline L93 — "public path misconfiguration ... | 500 + P1 alert | INTERNAL_AUTH_MISCONFIGURATION | INTERNAL" - code: INTERNAL_AUTH_MISCONFIGURATION category: INTERNAL http_status: 500 retryable: false retry_after_seconds: null owner_branch: feature-security-operational-baseline owner_layer: crosscut client_safe_message: "요청을 처리할 수 없습니다." runbook_link: "runbook://auth/public-path-misconfiguration" compatibility_impact: none required_test: contract-verification:auth-category # source: feature-container-runtime-contract L113 — "JVM OutOfMemoryError → ExitOnOutOfMemoryError로 137 exit, log에 error.code=JVM_OOM 명시" - code: JVM_OOM category: INTERNAL http_status: 500 retryable: false retry_after_seconds: null owner_branch: feature-container-runtime-contract owner_layer: infrastructure client_safe_message: "요청을 처리할 수 없습니다." runbook_link: "runbook://runtime/jvm-oom" compatibility_impact: none required_test: contract-verification:container-runtime-oom # ============================================================ # DB / 영속성 (feature-persistence-failure-baseline / SQLState Matrix) # ============================================================ # source: feature-persistence-failure-baseline L85 — "08* | all | TRANSIENT_DEPENDENCY | DB_UNAVAILABLE | true" - code: DB_UNAVAILABLE category: TRANSIENT_DEPENDENCY http_status: 503 retryable: true retry_after_seconds: 5 owner_branch: feature-persistence-failure-baseline owner_layer: infrastructure client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://db/unavailable" compatibility_impact: none required_test: contract-verification:persistence-mapping # source: feature-persistence-failure-baseline L86 — "40001 | Postgres/MySQL | CONFLICT | DB_SERIALIZATION_FAILURE | true" - code: DB_SERIALIZATION_FAILURE category: CONFLICT http_status: 409 retryable: true retry_after_seconds: 1 owner_branch: feature-persistence-failure-baseline owner_layer: infrastructure client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다." runbook_link: "runbook://db/serialization-failure" compatibility_impact: none required_test: contract-verification:persistence-mapping # source: feature-persistence-failure-baseline L87 — "40P01 | Postgres | CONFLICT | DB_DEADLOCK | true (backoff)" - code: DB_DEADLOCK category: CONFLICT http_status: 409 retryable: true retry_after_seconds: 1 owner_branch: feature-persistence-failure-baseline owner_layer: infrastructure client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다." runbook_link: "runbook://db/deadlock" compatibility_impact: none required_test: contract-verification:persistence-mapping # source: feature-persistence-failure-baseline L88 — "23502 | Postgres | DATA_INTEGRITY | DB_NULL_VIOLATION | false" - code: DB_NULL_VIOLATION category: DATA_INTEGRITY http_status: 409 retryable: false retry_after_seconds: null owner_branch: feature-persistence-failure-baseline owner_layer: infrastructure client_safe_message: "요청을 처리할 수 없습니다." runbook_link: null compatibility_impact: none required_test: contract-verification:persistence-mapping # source: feature-persistence-failure-baseline L89 — "23503 | Postgres | DATA_INTEGRITY | DB_FK_VIOLATION | false" - code: DB_FK_VIOLATION category: DATA_INTEGRITY http_status: 409 retryable: false retry_after_seconds: null owner_branch: feature-persistence-failure-baseline owner_layer: infrastructure client_safe_message: "요청을 처리할 수 없습니다." runbook_link: null compatibility_impact: none required_test: contract-verification:persistence-mapping # source: feature-persistence-failure-baseline L90 — "23505 | Postgres | CONFLICT | DB_UNIQUE_VIOLATION | false (business mapping)" - code: DB_UNIQUE_VIOLATION category: CONFLICT http_status: 409 retryable: false retry_after_seconds: null owner_branch: feature-persistence-failure-baseline owner_layer: infrastructure client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다." runbook_link: null compatibility_impact: none required_test: contract-verification:persistence-mapping # source: feature-persistence-failure-baseline L91 — "23514 | Postgres | DATA_INTEGRITY | DB_CHECK_VIOLATION | false" - code: DB_CHECK_VIOLATION category: DATA_INTEGRITY http_status: 409 retryable: false retry_after_seconds: null owner_branch: feature-persistence-failure-baseline owner_layer: infrastructure client_safe_message: "요청을 처리할 수 없습니다." runbook_link: null compatibility_impact: none required_test: contract-verification:persistence-mapping # source: feature-persistence-failure-baseline L92 — "25P03 | Postgres | TRANSIENT_DEPENDENCY | DB_IDLE_IN_TX_TIMEOUT | true" - code: DB_IDLE_IN_TX_TIMEOUT category: TRANSIENT_DEPENDENCY http_status: 503 retryable: true retry_after_seconds: 2 owner_branch: feature-persistence-failure-baseline owner_layer: infrastructure client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://db/idle-in-tx-timeout" compatibility_impact: none required_test: contract-verification:persistence-mapping # source: feature-persistence-failure-baseline L93 — "57014 | Postgres | TRANSIENT_DEPENDENCY | DB_QUERY_CANCELED | false" - code: DB_QUERY_CANCELED category: TRANSIENT_DEPENDENCY http_status: 503 retryable: false retry_after_seconds: null owner_branch: feature-persistence-failure-baseline owner_layer: infrastructure client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://db/query-canceled" compatibility_impact: none required_test: contract-verification:persistence-mapping # source: review-followup P15 (S2-lead-4) — JPA OPTIMISTIC_CONFLICT (flush·commit 때 @Version 검사 실패) - code: DB_OPTIMISTIC_CONFLICT category: CONFLICT http_status: 409 retryable: false retry_after_seconds: null owner_branch: feature-persistence-failure-baseline owner_layer: infrastructure client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다." runbook_link: null compatibility_impact: additive required_test: persistence-jpa:JpaPersistenceExceptionCodeTest # source: review-followup P15 (S2-lead-4) — JPA COMPLETION_UNKNOWN (40003 / commit 단계 연결 끊김) - code: DB_COMPLETION_UNKNOWN category: DATA_INTEGRITY http_status: 500 retryable: false retry_after_seconds: null owner_branch: feature-persistence-failure-baseline owner_layer: infrastructure client_safe_message: "요청을 처리할 수 없습니다." runbook_link: null compatibility_impact: additive required_test: persistence-jpa:JpaPersistenceExceptionCodeTest # ============================================================ # Rate limit / Idempotency (feature-rate-limit-idempotency-contract) # ============================================================ # source: feature-rate-limit-idempotency-contract — rate limit 응답·로그 기준 / Retry-After 헤더 기준 (scope L29, L33) - code: RATE_LIMIT_EXCEEDED category: RATE_LIMIT http_status: 429 retryable: true retry_after_seconds: 1 owner_branch: feature-rate-limit-idempotency-contract owner_layer: presentation client_safe_message: "요청이 너무 잦습니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://rate-limit/exceeded" compatibility_impact: none required_test: contract-verification:rate-limit # source: 2026-11-12 리뷰 결정 ② — 서버 포화(허가 상한, 꽉 찬 work pool)는 전송마다 다른 코드였다(web-advanced # ADMISSION_REFUSED 503, fileserver TRANSFER_ADMISSION_REJECTED 429, gRPC RATE_LIMIT_EXCEEDED). 이 코드 하나로 모은다. # 호출자 자신의 빈도·동시성 초과만 429(RATE_LIMIT_EXCEEDED, fileserver TRANSFER_ADMISSION_REJECTED)다. - code: SERVER_BUSY category: TRANSIENT_DEPENDENCY http_status: 503 retryable: true retry_after_seconds: 1 owner_branch: 2026-11-12-round9-review owner_layer: presentation client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://server/busy" compatibility_impact: behavior-change required_test: contract-verification:server-saturation # source: docs/web/http-contract.md §2 (2026-11-01 소유자 결정, 리뷰 02-01 대안 A) — 결과 불명. 같은 Idempotency-Key로 Retry-After 뒤 재전송. 새 키 금지. # 2초 = 기본 processing lease(30s)보다 짧은 고정값. 이전 "client는 polling"(retryable=false)은 조회 엔드포인트가 없어 폐기. # 값 하나: IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER. processing-lease가 이 값 이하면 기동 실패(재리뷰 RR-02-05). # behavior-change: retryable false→true는 web Envelope뿐 아니라 gRPC trailer error-retryable(status ABORTED)과 # GraphQL extension retryable에도 나간다(재리뷰 RR-02-06, GrpcStatusMapperTest·GraphQlWireErrorMapperTest가 고정). - code: IDEMPOTENT_IN_FLIGHT category: CONFLICT http_status: 409 retryable: true retry_after_seconds: 2 owner_branch: feature-rate-limit-idempotency-contract owner_layer: application client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다." runbook_link: null compatibility_impact: behavior-change required_test: contract-verification:idempotency # source: feature-rate-limit-idempotency-contract L72 — "fingerprint mismatch (same key + different body) = 422 IDEMPOTENT_REQUEST_MISMATCH" - code: IDEMPOTENT_REQUEST_MISMATCH category: VALIDATION http_status: 422 retryable: false retry_after_seconds: null owner_branch: feature-rate-limit-idempotency-contract owner_layer: application client_safe_message: "요청 값이 올바르지 않습니다." runbook_link: null compatibility_impact: none required_test: contract-verification:idempotency # source: review-followup P15 (X2-P2-2a) — IdempotencyExecutor가 동작 전에 닫힌 채 거절한다(fail-closed) - code: IDEMPOTENCY_UNAVAILABLE category: TRANSIENT_DEPENDENCY http_status: 503 retryable: true retry_after_seconds: null owner_branch: feature-rate-limit-idempotency-contract owner_layer: application client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://idempotency/unavailable" compatibility_impact: additive required_test: contract-verification:idempotency # source: 재리뷰 2026-11-03 README 4절 결정, RR-02-03 — action이 돈 뒤 complete 단계에서 저장소가 응답하지 않음. # 실행 전 거부(IDEMPOTENCY_UNAVAILABLE)와 code로 구분한다. 결과 불명: 같은 키로 재전송하면 서버가 replay·in-flight· # recovery-required로 판정한다. 새 키 금지. docs/web/http-contract.md §2. - code: IDEMPOTENCY_COMPLETION_UNKNOWN category: TRANSIENT_DEPENDENCY http_status: 503 retryable: true retry_after_seconds: null owner_branch: feature-rate-limit-idempotency-contract owner_layer: application client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://idempotency/unavailable" compatibility_impact: additive required_test: contract-verification:idempotency # source: review-followup P15 (X2-P2-2a) — replay가 외부 효과가 일어났는지 정할 수 없다 - code: IDEMPOTENCY_RECOVERY_REQUIRED category: DATA_INTEGRITY http_status: 500 retryable: false retry_after_seconds: null owner_branch: feature-rate-limit-idempotency-contract owner_layer: application client_safe_message: "요청을 처리할 수 없습니다." runbook_link: "runbook://idempotency/unavailable" compatibility_impact: additive required_test: contract-verification:idempotency # ============================================================ # 파일 / 자원 (feature-file-resource-handling-contract) # ============================================================ # source: feature-file-resource-handling-contract L69 — "spring.servlet.multipart.max-file-size 10MB ... Spring 단의 enforcement가 실패 시 envelope 응답 보장" / 테스트 계약 "oversized upload가 generic 500으로 처리되면 실패" # ============================================================ # API 계약의 전송 표준 코드 (feature-api-contract-baseline) # ============================================================ # 참고: 전송 모양 실패의 분류는 feature-api-contract-baseline이 가진다 # (D8 413/414, D9 406/415, D12 405, D15 412). 이 행들은 dev.caskeleton.shared.error.OperationalError를 # 그대로 옮긴 것이다. D11 상태 대응 일관성 테스트(소유: 이 branch, 생산자)가 코드의 레지스트리 http_status와 # enum httpStatus()가 어긋나면 빌드를 실패시킨다. # source: feature-api-contract-baseline.md D12 — "405 Method Not Allowed + Allow header 의무" - code: METHOD_NOT_ALLOWED category: VALIDATION http_status: 405 retryable: false retry_after_seconds: null owner_branch: feature-api-contract-baseline owner_layer: presentation client_safe_message: "요청 값이 올바르지 않습니다." runbook_link: null compatibility_impact: none required_test: contract-verification:api-contract-status-mapping # source: feature-api-contract-baseline.md D9 — "406 Not Acceptable = 응답 표현 협상 실패" - code: NOT_ACCEPTABLE category: VALIDATION http_status: 406 retryable: false retry_after_seconds: null owner_branch: feature-api-contract-baseline owner_layer: presentation client_safe_message: "요청 값이 올바르지 않습니다." runbook_link: null compatibility_impact: none required_test: contract-verification:api-contract-status-mapping # source: feature-api-contract-baseline.md D15 — "If-Match mismatch 시 412 Precondition Failed" - code: PRECONDITION_FAILED category: CONFLICT http_status: 412 retryable: false retry_after_seconds: null owner_branch: feature-api-contract-baseline owner_layer: presentation client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다." runbook_link: null compatibility_impact: none required_test: contract-verification:api-contract-status-mapping # source: feature-api-contract-baseline.md D8 — "request size limit 실패 분류 (413)" - code: PAYLOAD_TOO_LARGE category: VALIDATION http_status: 413 retryable: false retry_after_seconds: null owner_branch: feature-api-contract-baseline owner_layer: presentation client_safe_message: "요청 값이 올바르지 않습니다." runbook_link: null compatibility_impact: none required_test: contract-verification:api-contract-status-mapping # source: feature-api-contract-baseline.md D8 형제 — "URI 길이 실패 분류 (414)" # 참고: 강제는 Tomcat·gateway가 한다(Spring dispatch 전에 거절). 이 행과 코드는 상태 대응 일관성을 위해 # 있다. 끝에서 끝까지의 414 계약 테스트는 `planned`다 (gateway/Tomcat maxHttpHeaderSize 8KB 경계). - code: URI_TOO_LONG category: VALIDATION http_status: 414 retryable: false retry_after_seconds: null owner_branch: feature-api-contract-baseline owner_layer: presentation client_safe_message: "요청 값이 올바르지 않습니다." runbook_link: null compatibility_impact: none required_test: contract-verification:api-contract-status-mapping # source: feature-api-contract-baseline.md D9 — "415 Unsupported Media Type = 요청 본문 format 미지원" - code: UNSUPPORTED_MEDIA_TYPE category: VALIDATION http_status: 415 retryable: false retry_after_seconds: null owner_branch: feature-api-contract-baseline owner_layer: presentation client_safe_message: "요청 값이 올바르지 않습니다." runbook_link: null compatibility_impact: none required_test: contract-verification:api-contract-status-mapping # ============================================================ # Tenant (feature-tenant-context-policy) # ============================================================ # source: feature-tenant-context-policy L71 — "tenant 미지원 모드에서 X-Tenant-Id 헤더 수신 시 400 TENANT_NOT_SUPPORTED (filter 단계)" # ============================================================ # Validation / Business rule (feature-business-rule-validation-contract) # ============================================================ # NOTE: business-rule-validation branch는 mapping 규칙 SSOT (syntax→VALIDATION, # policy→AUTHZ/CONFLICT, invariant→CONFLICT/VALIDATION, persistence→PERSISTENCE/CONFLICT) # 이며 구체 code는 example로 VALIDATION_EMAIL_FORMAT만 등장 # (feature-operational-error-observability-foundation L110). 실제 도메인별 code는 # Phase D(도메인 feature 적용) 시 본 registry에 추가. # source: feature-operational-error-observability-foundation L110 — "code: VALIDATION_EMAIL_FORMAT, // registry-registered code" (validation 필드 오류 JSON 모양 예) # ============================================================ # 캐시 (feature-cache-consistency-contract) # ============================================================ # source: feature-cache-consistency-contract — Decisionized Work Items "Redis unavailable | degrade only if declared | fail-fast for required cache | generic INTERNAL | unavailable mapping" / 테스트 "Redis unavailable이 degrade 가능 여부 없이 INTERNAL로 처리되면 실패" # ============================================================ # 외부 HTTP 호출 (feature-outbound-http-client-baseline) # ============================================================ # source: feature-outbound-http-client-baseline L70 — "outbound HTTP timeout default = connect 2s / read 5s / global call 10s" + scope "timeout/connect/DNS failure 분류" / 테스트 "upstream timeout은 retryable dependency failure로 분류되어야 함" - code: DEPENDENCY_TIMEOUT category: TRANSIENT_DEPENDENCY http_status: 504 retryable: true retry_after_seconds: 2 owner_branch: feature-outbound-http-client-baseline owner_layer: infrastructure client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://dependency/timeout" compatibility_impact: none required_test: contract-verification:outbound-http # source: feature-outbound-http-client-baseline — scope "timeout/connect/DNS failure 분류" + L70 connect=2s timeout - code: DEPENDENCY_CONNECT_FAILED category: TRANSIENT_DEPENDENCY http_status: 503 retryable: true retry_after_seconds: 2 owner_branch: feature-outbound-http-client-baseline owner_layer: infrastructure client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://dependency/connect-failed" compatibility_impact: none required_test: contract-verification:outbound-http # source: feature-outbound-http-client-baseline — scope "timeout/connect/DNS failure 분류" - code: DEPENDENCY_DNS_FAILED category: TRANSIENT_DEPENDENCY http_status: 503 retryable: true retry_after_seconds: 5 owner_branch: feature-outbound-http-client-baseline owner_layer: infrastructure client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://dependency/dns-failed" compatibility_impact: none required_test: contract-verification:outbound-http # source: feature-outbound-http-client-baseline — scope "upstream 4xx/5xx 분류" / 테스트 "401/403은 credential/scope/config 문제로 분류되어야 함" - code: DEPENDENCY_4XX_CLIENT category: PERMANENT_DEPENDENCY http_status: 502 retryable: false retry_after_seconds: null owner_branch: feature-outbound-http-client-baseline owner_layer: infrastructure client_safe_message: "요청을 처리할 수 없습니다." runbook_link: "runbook://dependency/4xx-client" compatibility_impact: none required_test: contract-verification:outbound-http # source: feature-outbound-http-client-baseline — scope "upstream 4xx/5xx 분류" - code: DEPENDENCY_5XX_SERVER category: TRANSIENT_DEPENDENCY http_status: 502 retryable: true retry_after_seconds: 2 owner_branch: feature-outbound-http-client-baseline owner_layer: infrastructure client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://dependency/5xx-server" compatibility_impact: none required_test: contract-verification:outbound-http # source: feature-outbound-http-client-baseline L69 — "circuit breaker metric은 dependency.name, dependency.type, outcome까지만 tag로 허용" + Decisionized "circuit breaker | Resilience4j optional env" - code: DEPENDENCY_CIRCUIT_OPEN category: TRANSIENT_DEPENDENCY http_status: 503 retryable: true retry_after_seconds: 10 owner_branch: feature-outbound-http-client-baseline owner_layer: infrastructure client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://dependency/circuit-open" compatibility_impact: none required_test: contract-verification:outbound-http # ============================================================ # Outbox (feature-domain-event-outbox-contract) # ============================================================ # source: feature-domain-event-outbox-contract L67 — "outbox row status enum = PENDING / IN_FLIGHT / PUBLISHED / FAILED / DEAD" + scope "publish 실패 분류" / 판정 "publish 실패가 retry/DLQ/log/runbook 기준 없이 삼켜지면 실패" - code: OUTBOX_PUBLISH_FAILED category: TRANSIENT_DEPENDENCY http_status: 500 retryable: true retry_after_seconds: 30 owner_branch: feature-domain-event-outbox-contract owner_layer: infrastructure client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://outbox/publish-failed" compatibility_impact: none required_test: contract-verification:outbox-publish # source: feature-domain-event-outbox-contract L67 — outbox status enum "DEAD" / Outbox Defaults "DLQ | background-job branch owner" - code: OUTBOX_DEAD_LETTER category: INTERNAL http_status: 500 retryable: false retry_after_seconds: null owner_branch: feature-domain-event-outbox-contract owner_layer: infrastructure client_safe_message: "요청을 처리할 수 없습니다." runbook_link: "runbook://outbox/dead-letter" compatibility_impact: none required_test: contract-verification:outbox-dlq # ============================================================ # 백그라운드 작업 / 비동기 (feature-background-job-async-contract) # ============================================================ # source: feature-background-job-async-contract — Decisionized "saturation | bounded executor + rejection log" / L72 "saturation policy default = AbortPolicy" / 테스트 "executor rejection이 structured log 없이 발생하면 실패" - code: JOB_EXECUTOR_REJECTED category: TRANSIENT_DEPENDENCY http_status: 503 retryable: true retry_after_seconds: 5 owner_branch: feature-background-job-async-contract owner_layer: infrastructure client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://job/executor-rejected" compatibility_impact: none required_test: contract-verification:async-saturation # source: feature-background-job-async-contract L69 — "기본 backoff는 exponential backoff with jitter, max attempts 3, DLQ after exhausted attempts" + scope "shutdown 중 job 처리 기준" / L73 graceful shutdown ≤19s - code: JOB_TIMEOUT category: TRANSIENT_DEPENDENCY http_status: 500 retryable: true retry_after_seconds: 10 owner_branch: feature-background-job-async-contract owner_layer: infrastructure client_safe_message: "일시적인 오류입니다. 잠시 후 다시 시도해 주세요." runbook_link: "runbook://job/timeout" compatibility_impact: none required_test: contract-verification:async-timeout # source: feature-background-job-async-contract L69 — "DLQ after exhausted attempts" + Decisionized "retry/DLQ | exp backoff jitter, max 3, DLQ exhausted | ... | infinite retry" - code: JOB_DEAD_LETTER category: INTERNAL http_status: 500 retryable: false retry_after_seconds: null owner_branch: feature-background-job-async-contract owner_layer: infrastructure client_safe_message: "요청을 처리할 수 없습니다." runbook_link: "runbook://job/dead-letter" compatibility_impact: none required_test: contract-verification:async-dlq # ============================================================ # 분산 lock (feature-distributed-lock-contract) # ============================================================ # source: feature-distributed-lock-contract D7 — "lock 획득 실패/timeout 의 error code = # LOCK_ACQUISITION_TIMEOUT (category CONFLICT, retryable true, client_safe true) + metric # lock.acquisition" / D5 — "try-lock + 유한 waitTime + lease(TTL) 필수, 무한 blocking 금지". # category CONFLICT 는 기존 enum 재사용; retryable=true — 락 보유자가 임계 구역을 빠져나오면 # 동일 요청 재시도로 해소된다(transient contention). DB_DEADLOCK / DB_SERIALIZATION_FAILURE 와 # 같은 retryable CONFLICT 계열(409). 본 코드는 distributedLockProvider 획득 timeout 전용이며 # cache stampede lock 의 CACHE_STAMPEDE_LOCK_TIMEOUT(cache-consistency, TRANSIENT_DEPENDENCY 503) # 과 의미가 구분된다 — 후자는 캐시 백엔드 의존성 timeout, 전자는 분산 상호배제 contention. - code: LOCK_ACQUISITION_TIMEOUT category: CONFLICT http_status: 409 retryable: true retry_after_seconds: 1 owner_branch: feature-distributed-lock-contract owner_layer: infrastructure client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다." runbook_link: "runbook://lock/acquisition-timeout" compatibility_impact: none required_test: contract-verification:lock-acquisition-timeout # ============================================================ # Migration / 기동 (feature-migration-startup-contract) # ============================================================ # source: feature-migration-startup-contract L71 — "startup exit code 표준 = ... migration 실패=70 ..." + Decisionized "startup failure log | structured log with startup.phase, error.code, error.category" - code: ADAPTER_DISABLED category: INTERNAL http_status: 500 retryable: false retry_after_seconds: null owner_branch: feature-integration-adapter-templates owner_layer: infrastructure client_safe_message: "요청을 처리할 수 없습니다." runbook_link: "runbook://adapter/adapter-disabled" compatibility_impact: none required_test: adapter-contract:adapter-disabled-runtime-call # source: feature-migration-startup-contract L71 — "startup exit code 표준 = ... profile mismatch=71" / 테스트 "prod profile에서 local-only 설정이 켜지면 실패" # ============================================================ # 관리 포트 / Actuator (feature-management-actuator-security-contract) # ============================================================ # source: feature-management-actuator-security-contract — Exposure Policy "env/configprops | forbidden" "heapdump/threaddump | forbidden unless break-glass runbook" "shutdown | forbidden" / 테스트 "prod에서 env/configprops endpoint가 노출되면 실패" - code: ACTUATOR_FORBIDDEN category: AUTHZ http_status: 403 retryable: false retry_after_seconds: null owner_branch: feature-management-actuator-security-contract owner_layer: presentation client_safe_message: "이 작업을 수행할 권한이 없습니다." runbook_link: "runbook://management/actuator-forbidden" compatibility_impact: none required_test: contract-verification:management-actuator # ============================================================ # 지금 코드와 맞춤 (2026-09-21) # 코드에는 있었지만 Phase-B 레지스트리에 없던 저장소 전체 OperationalError 항목. 제품별 ApiErrorCode enum은 # 자기 제품 모듈이 가진다. # ============================================================ - code: VALIDATION_FAILED category: VALIDATION http_status: 400 retryable: false retry_after_seconds: null owner_branch: 2026-09-21-core-web-review-remediation owner_layer: application client_safe_message: "요청 값이 올바르지 않습니다." runbook_link: null compatibility_impact: additive required_test: contract-verification:operational-error-registry - code: BAD_PARAMETER category: VALIDATION http_status: 400 retryable: false retry_after_seconds: null owner_branch: 2026-09-21-core-web-review-remediation owner_layer: presentation client_safe_message: "요청 값이 올바르지 않습니다." runbook_link: null compatibility_impact: additive required_test: contract-verification:operational-error-registry - code: MAPPING_FAILED category: VALIDATION http_status: 400 retryable: false retry_after_seconds: null owner_branch: 2026-09-21-core-web-review-remediation owner_layer: presentation client_safe_message: "요청 값이 올바르지 않습니다." runbook_link: null compatibility_impact: additive required_test: contract-verification:operational-error-registry - code: BATCH_PARTIAL_FAILURE category: VALIDATION http_status: 200 retryable: false retry_after_seconds: null owner_branch: 2026-09-21-core-web-review-remediation owner_layer: application client_safe_message: "요청 값이 올바르지 않습니다." runbook_link: null compatibility_impact: additive required_test: contract-verification:operational-error-registry - code: INTERNAL_ERROR category: INTERNAL http_status: 500 retryable: false retry_after_seconds: null owner_branch: 2026-09-21-core-web-review-remediation owner_layer: crosscut client_safe_message: "요청을 처리할 수 없습니다." runbook_link: "runbook://internal/error-spike" compatibility_impact: additive required_test: contract-verification:operational-error-registry - code: UNAUTHENTICATED category: AUTH http_status: 401 retryable: false retry_after_seconds: null owner_branch: 2026-09-21-core-web-review-remediation owner_layer: presentation client_safe_message: "인증이 필요합니다." runbook_link: "runbook://auth/token-missing" compatibility_impact: additive required_test: contract-verification:operational-error-registry - code: INVALID_TOKEN category: AUTH http_status: 401 retryable: false retry_after_seconds: null owner_branch: 2026-09-21-core-web-review-remediation owner_layer: presentation client_safe_message: "인증이 필요합니다." runbook_link: "runbook://auth/token-malformed" compatibility_impact: additive required_test: contract-verification:operational-error-registry - code: FORBIDDEN category: AUTHZ http_status: 403 retryable: false retry_after_seconds: null owner_branch: 2026-09-21-core-web-review-remediation owner_layer: presentation client_safe_message: "이 작업을 수행할 권한이 없습니다." runbook_link: "runbook://authz/insufficient-permission" compatibility_impact: additive required_test: contract-verification:operational-error-registry - code: ROUTE_NOT_FOUND category: NOT_FOUND http_status: 404 retryable: false retry_after_seconds: null owner_branch: 2026-09-21-core-web-review-remediation owner_layer: presentation client_safe_message: "요청한 리소스를 찾을 수 없습니다." runbook_link: null compatibility_impact: additive required_test: contract-verification:operational-error-registry - code: DB_LOCK_TIMEOUT category: CONFLICT http_status: 409 retryable: false retry_after_seconds: null owner_branch: 2026-09-21-core-web-review-remediation owner_layer: infrastructure client_safe_message: "현재 상태에서는 요청을 처리할 수 없습니다." runbook_link: null compatibility_impact: additive required_test: contract-verification:operational-error-registry