Files
clean-architecture-backend-…/docs/runbooks/idempotency-unavailable.md
T
donghyeon-kaandClaude Opus 5.5 c4a066df41 review-followup Wave 3 라운드 1(P15): 에러 어휘를 Envelope·ApiErrorCode·한국어 Category 문구 표 하나로
- HTTP 에러는 Envelope 하나(결정 2): fileserver problem+json 제거, tus 헤더만 유지, Draft-12 offset 문서는 프로토콜 예외(결정 12)
- shared-contract `ClientErrorMessages`(Category별 한국어, 결정 11), shared 예외 `ApiErrorCarrier`, web 일반 carrier 분기
- GraphQL: category switch 3개 → 표 하나, 요청 단계·body-limit·DataLoader 코드가 mapper 경유, 등록된 코드만 노출(결정 25)
- gRPC trailer `retryable`, STOMP carrier 코드 보존, IAE는 모든 전송 400 계열, JpaPersistenceException → PersistenceFailureException
- sample 이벤트 JSON escape를 `EventJson` 하나로
- 통합 충돌 3건(gRPC 인터셉터 import, sample 409 핸들러·테스트를 새 문구 표 방식으로), P14 GraphQL 테스트 import 경로 수정

검증: ./gradlew check architectureCheck verifyPublicPathSnapshot verifyDependencyLocks --continue 통과(598 task)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-28 15:53:29 +09:00

1.9 KiB

title, category, error_codes, severity, owner, last_updated, status
title category error_codes severity owner last_updated status
Runbook — IDEMPOTENCY_UNAVAILABLE (멱등성 조정 저장소 사용 불가) TRANSIENT_DEPENDENCY
IDEMPOTENCY_UNAVAILABLE
IDEMPOTENCY_RECOVERY_REQUIRED
P2 oncall 2026-09-28 active

Runbook: IDEMPOTENCY_UNAVAILABLE (runbook://idempotency/unavailable)

Symptoms

  • HTTP 503 (error.code=IDEMPOTENCY_UNAVAILABLE, retryable=true) on endpoints that take an Idempotency-Key; the same code on the gRPC error-code trailer (UNAVAILABLE).
  • IdempotencyExecutor refused to run the action because the replay store (JPA or Redis, whichever app.idempotency selects) did not answer. Nothing was executed: the refusal happens before the action, so a client retry is safe.
  • HTTP 500 IDEMPOTENCY_RECOVERY_REQUIRED (retryable=false) means the opposite case: the store cannot tell whether an earlier attempt's external effect already happened.

Diagnosis

  • Check the health of the idempotency store the service uses (/actuator/health component of the JPA datasource or Redis, depending on the selected provider).
  • Look for connection-pool saturation or timeouts on that store in the same time window; the executor reports saturation as unavailable rather than guessing.
  • For IDEMPOTENCY_RECOVERY_REQUIRED, find the scope digest in the server log line of the failed request and inspect that record's state in the store.

Action

  • IDEMPOTENCY_UNAVAILABLE: restore the store; clients retry with the same key and backoff.
  • IDEMPOTENCY_RECOVERY_REQUIRED: do not ask the client to retry blindly. Confirm whether the downstream effect of the earlier attempt exists, then complete or release the record so the next request with that key replays or re-executes deterministically.

Escalation

  • P2 → P1 when the store stays unavailable for more than 10 minutes on a write path.
  • Page the owner of the idempotency store (database or Redis on-call).