--- 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).