- 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>
43 lines
1.9 KiB
Markdown
43 lines
1.9 KiB
Markdown
---
|
|
title: Runbook — IDEMPOTENCY_UNAVAILABLE (멱등성 조정 저장소 사용 불가)
|
|
category: TRANSIENT_DEPENDENCY
|
|
error_codes: [IDEMPOTENCY_UNAVAILABLE, IDEMPOTENCY_RECOVERY_REQUIRED]
|
|
severity: P2
|
|
owner: oncall
|
|
last_updated: 2026-09-28
|
|
status: 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).
|