pr / done (pull_request) Canceled after 0s
runbook이 코드가 내지 않는 신호로 장애를 찾게 한다. actuator·cross-tenant runbook은 아무 코드도 내지 않는 ACTUATOR_FORBIDDEN·AUTHZ_TENANT_MISMATCH를 증상으로 적고, 없는 경보·지표·로그 칸을 적는다. auth runbook은 로그에서 token payload·Authorization 원문을 보라고 하고(남지도 않고 남겨서도 안 된다), 없는 JWKS 캐시 손잡이와 decoder가 읽지 않는 Spring issuer 키를 적는다. rate-limit·dependency runbook은 없는 gateway 지표·헤더· CACHE_UNAVAILABLE·dependency_name 칸을, web runbook은 연산마다의 TTL, 시험 도구 GracefulShutdownProbe, 없는 tag routeTemplate, 기동이 거부하는 CORS 설정을 「기동은 된다」고 적는다. job runbook은 내는 코드가 없는 JOB_DEAD_LETTER·JOB_TIMEOUT과 job.* 지표에 경보를 걸게 한다. 각 runbook을 지금 코드가 내는 신호로 다시 쓴다: 응답 코드·헤더, 보안 로그 줄 `security failure: code=… path=…`, 요청 로그 줄, ServerFailureLog 의 고정 문구(`dependency failure classified as … dependency=<이름>`, `persistence failure classified as …`), 실제 설정 키 APP_SECURITY_JWT_ISSUER, registry에 있는 지표. 이 템플릿에 경보 규칙이 없다는 것, 내는 코드가 없는 코드·지표는 서비스가 낼 때만 있다는 것을 적는다. 진단 순서도 고친다: actuator 노출은 관리 포트 9001로 가르고, INTERNAL_AUTH_MISCONFIGURATION은 issuer discovery(4xx·issuer 불일치· jwks_uri 없음은 500, 연결 실패·5xx·JSON 아님은 503)부터, 종료 예산은 웹 drain 30s + async 19s + preStop의 합으로 본다. 같은 원인의 다른 자리(경보 이름을 지어 적은 job·outbox·internal-error-spike, traceId로 적은 칸, 지적 밖 auth·dependency·db·outbox runbook, error-codes.yaml 주석, 같은 틀린 신호를 적은 shared-contract README·web README· DependencyFailureException Javadoc)도 고치고, 본문의 리뷰 ID는 지운다. 버린 안: 선언만 있는 두 코드를 내는 WARN·counter를 새로 만들기. actuator 노출 밖 경로는 메인 chain이 401 AUTH_TOKEN_MISSING(익명)·404(인증됨)로 답해 403 상황이 없고, cross-tenant는 정한 규칙(남의 것은 404)이라 판정 자리가 서비스 코드에 있다. 새 신호는 서비스가 더할 일로 runbook에 적는다. 위험: 문서만 바뀐다. runbook은 모두 status 초안으로 둔다. dependency-unavailable이 적은 hikaricp.connections.pending·timeout 행과 job.* 행의 emitted_when은 관측 registry 변경(같은 묶음의 다른 PR)이 더하고, auth-jwks-unavailable의 「캐시가 지난 뒤 503」은 인증 PR의 JWKS 재조회 분류 수정이 만든다. 세 PR을 함께 병합한다. 검증: python3 scripts/check-docs.py·check-work-docs.py OK, desktop :app-bootstrap:documentContractTest :app-bootstrap:repositoryContractTest, scripts/verify.sh pr rc=0. Refs: RR9-02-04, RR9-02-24, RR9-04-34, RR9-04-37
923 lines
42 KiB
YAML
923 lines
42 KiB
YAML
# 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"
|
|
# 지금 이 코드는 JWT decoder를 만들지 못할 때(issuer discovery 4xx·issuer 불일치·jwks_uri 없음) 나온다. 공개 경로
|
|
# 설정 오류는 이 코드를 내지 않는다(runbook auth-public-path-misconfiguration.md).
|
|
- 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
|