POST /orders
POST /payments
POST /case-escalations
POST /refunds
PATCH /cases/{id}/status
POST /documents/{id}/approve

- mobile network timeout,
- browser retry,
- load balancer connection reset,
- API Gateway 504,
- backend response hilang setelah commit,
- client tidak menerima response,
- user double click,
- worker retry,
- deployment restart,
- SDK retry,
- upstream event replay.

- order ganda,
- payment ganda,
- email ganda,
- status transition ganda,
- inventory berkurang dua kali,
- enforcement action tereksekusi dua kali,
- audit trail misleading,
- case lifecycle melompat state.

Idempotency bukan fitur HTTP.
Idempotency adalah invariant bisnis yang disimpan secara durable.

Command = permintaan untuk mengubah state.

CreateOrder,
ReserveInventory,
SubmitCase,
ApproveDocument,
EscalateInvestigation,
CreatePayment,
IssueRefund,
AssignInspector,
CloseEnforcementCase.

- memiliki intent,
- bisa diterima atau ditolak,
- bisa mengubah state,
- bisa memicu side effect,
- butuh authorization,
- butuh validation,
- butuh audit,
- sering butuh idempotency,
- sering punya lifecycle.

Operasi idempotent menghasilkan efek akhir yang sama walaupun dijalankan lebih dari sekali dengan input yang sama.

Untuk identity command yang sama dan payload semantik yang sama, sistem harus melakukan side effect paling banyak sekali, dan duplicate attempt harus mengembalikan hasil yang konsisten.

1. Same command identity.
2. Same semantic request.
3. Same durable outcome atau same observable status.

Request 1: Idempotency-Key: abc, amount=100
Request 2: Idempotency-Key: abc, amount=999

Gunakan requestId sebagai idempotency key.

Idempotency-Key stabil untuk logical command.
Request-Id berbeda untuk tiap technical attempt.
Correlation-Id mengikat semua attempt dalam user journey.

PROCESSING,
COMPLETED,
FAILED_RETRYABLE,
FAILED_FINAL,
AMBIGUOUS.

IN_PROGRESS,
COMPLETED,
FAILED.

1. Receive command request.
2. Authenticate and authorize caller.
3. Validate request shape.
4. Canonicalize semantic payload.
5. Compute request hash.
6. Try reserve idempotency record atomically.
7. If record already exists:
   a. If hash differs -> conflict.
   b. If completed -> return stored response/status.
   c. If processing -> return 202/409 depending contract.
   d. If failed retryable -> retry or resume safely.
   e. If ambiguous -> return status requiring reconciliation.
8. Execute domain transaction.
9. Store result and response summary.
10. Publish outbox/event or start workflow safely.
11. Return response.

1. Parse request.
2. Authenticate caller.
3. Authorize operation.
4. Validate shape and required fields.
5. Canonicalize semantic payload.
6. Build idempotency scope.
7. Reserve/check idempotency record.
8. Execute domain validation inside transaction.
9. Commit command result.

Approve case saat status = REVIEWED.
Retry command approval harus mengembalikan hasil command pertama,
bukan gagal karena status sekarang sudah APPROVED.

idempotency_key = abc

tenant_id + caller_id/client_id + operation + idempotency_key

UNIQUE (tenant_id, caller_id, operation, idempotency_key)

- false duplicate,
- cross-tenant leakage,
- denial of service,
- security issue,
- impossible debugging.

{"amount":100,"currency":"USD"}

{"currency":"USD","amount":100}

- normalize field order,
- remove ignored fields,
- normalize numeric precision,
- normalize timestamps bila contract mengizinkan,
- include operation name,
- include caller/tenant scope,
- include version bila schema berubah.

String canonical = canonicalJson(Map.of(
    "operation", "CreatePayment",
    "tenantId", tenantId,
    "callerId", callerId,
    "amount", money.amountMinorUnits(),
    "currency", money.currency(),
    "orderId", orderId
));

String requestHash = sha256(canonical);

requestId,
traceId,
signature timestamp,
client local timestamp,
headers yang tidak memengaruhi semantics.

CREATE TABLE api_command_idempotency (
    id BIGSERIAL PRIMARY KEY,
    tenant_id VARCHAR(64) NOT NULL,
    caller_id VARCHAR(128) NOT NULL,
    operation VARCHAR(128) NOT NULL,
    idempotency_key VARCHAR(256) NOT NULL,
    request_hash CHAR(64) NOT NULL,
    command_id UUID NOT NULL,
    aggregate_type VARCHAR(128),
    aggregate_id VARCHAR(128),
    status VARCHAR(32) NOT NULL,
    http_status INT,
    response_body JSONB,
    error_code VARCHAR(128),
    locked_until TIMESTAMPTZ,
    expires_at TIMESTAMPTZ NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    UNIQUE (tenant_id, caller_id, operation, idempotency_key)
);

CREATE INDEX idx_api_command_expiry
    ON api_command_idempotency (expires_at);

CREATE INDEX idx_api_command_status
    ON api_command_idempotency (status, updated_at);

INSERT INTO api_command_idempotency (
    tenant_id,
    caller_id,
    operation,
    idempotency_key,
    request_hash,
    command_id,
    status,
    expires_at
)
VALUES (?, ?, ?, ?, ?, ?, 'PROCESSING', now() + interval '24 hours')
ON CONFLICT (tenant_id, caller_id, operation, idempotency_key)
DO NOTHING;

Unique constraint adalah lock-free correctness primitive.
Jangan implementasikan idempotency dengan read-then-insert tanpa unique constraint.

BEGIN;

-- reserve idempotency record or lock existing
-- validate current aggregate state
-- update domain tables
-- write outbox event
-- update idempotency record COMPLETED + response summary

COMMIT;

- atomic,
- sederhana untuk relational DB,
- outbox bisa satu transaction,
- failure semantics lebih jelas.

- transaksi bisa menjadi besar bila response body besar,
- tidak cocok bila side effect external dilakukan di tengah transaction,
- contention jika command store terlalu hot.

1. Reserve idempotency record.
2. Execute domain transaction.
3. Update idempotency record with outcome.

Ada gap antara domain commit dan idempotency completion update.

PK = TENANT#{tenantId}#CALLER#{callerId}#OP#{operation}
SK = IDEMPOTENCY#{idempotencyKey}

requestHash,
commandId,
status,
httpStatus,
responseSummary,
errorCode,
expiresAt,
createdAt,
updatedAt,
lockExpiresAt.

{
  "TableName": "ApiCommandIdempotency",
  "Item": {
    "pk": {"S": "TENANT#t1#CALLER#c1#OP#CreatePayment"},
    "sk": {"S": "IDEMPOTENCY#abc"},
    "requestHash": {"S": "..."},
    "commandId": {"S": "cmd-123"},
    "status": {"S": "PROCESSING"},
    "expiresAt": {"N": "1780000000"}
  },
  "ConditionExpression": "attribute_not_exists(pk) AND attribute_not_exists(sk)"
}

{
  "status": "PROCESSING",
  "commandId": "cmd-123",
  "statusUrl": "/commands/cmd-123",
  "retryable": true,
  "retryAfterSeconds": 2
}

Duplicate -> return exactly same HTTP status and response body.

- create payment,
- create order,
- create resource,
- command yang response-nya kecil.

- resource state bisa berubah setelah command,
- response original tidak perlu identik,
- contract menyatakan response adalah current representation.

{
  "commandId": "cmd-123",
  "resourceId": "payment-789",
  "status": "SUCCEEDED"
}

FAILED_FINAL,
FAILED_RETRYABLE,
AMBIGUOUS.

charge payment,
send email,
submit government filing,
create third-party ticket,
publish irreversible notification,
call vendor that lacks idempotency.

1. Durable command record.
2. Durable side-effect attempt record.
3. Provider idempotency key bila tersedia.
4. Outbox/workflow untuk eksekusi side effect.
5. Reconciliation untuk ambiguous result.

POST /case-escalations
-> create command record
-> StartExecution Step Functions
-> return command/workflow status

- Express Workflows tidak punya idempotency StartExecution yang sama.
- Command response contract tetap perlu disimpan.
- Caller butuh status endpoint.
- Execution name uniqueness bukan pengganti domain invariant.
- Input canonicalization tetap perlu.

executionName = safeSlug(commandId or idempotencyScopeHash)

commandId -> stepFunctionsExecutionArn

- Lambda-backed API endpoint,
- async consumer,
- event handler,
- simple command handler,
- deterministic response replay.

Powertools membantu implementasi mekanik idempotency.
Ia tidak menggantikan desain command semantics, request hash, domain transaction, external side-effect reconciliation, dan status contract.

Apakah command yang sama dijalankan lebih dari sekali?

Apakah command ini masih valid terhadap versi aggregate saat ini?

PATCH /cases/case-123/status
Idempotency-Key: k-1
If-Match: "version-7"

- First attempt valid, update version 7 -> 8.
- Retry dengan key sama harus return original success.
- New command dengan key berbeda tapi If-Match version 7 harus gagal 412.

Berapa lama caller boleh retry?
Berapa lama duplicate request masih mungkin datang?
Berapa lama audit membutuhkan bukti?
Apakah command punya external irreversible side effect?
Apa konsekuensi jika key expired lalu request lama datang lagi?

- caller menebak idempotency key milik caller lain,
- response replay mengembalikan data milik tenant lain,
- status endpoint expose command existence,
- idempotency key disimpan mentah dan muncul di log,
- response body sensitif disimpan tanpa redaction,
- key tidak discoped by tenant/caller/operation.

- scope key dengan tenant/caller/operation,
- authorize sebelum lookup,
- hash idempotency key di logs,
- encrypt sensitive response if stored,
- store response summary, not full sensitive payload,
- avoid user-provided key as primary public identifier,
- use status endpoint authorization.

idempotency_reserve_success_count,
idempotency_duplicate_in_progress_count,
idempotency_duplicate_completed_count,
idempotency_conflict_count,
idempotency_ambiguous_count,
command_processing_duration_ms,
command_completion_count,
command_failed_final_count,
command_failed_retryable_count,
command_reconciliation_count,
external_side_effect_duplicate_prevented_count.

requestId,
correlationId,
tenantId bucket/hash,
operation,
idempotencyKeyHash,
requestHash,
commandId,
aggregateId,
statusBefore,
statusAfter,
httpStatus,
retryAttempt,
sideEffectProvider,
providerIdempotencyKeyHash,
errorCode.

API receive -> idempotency reserve -> domain transaction -> outbox/workflow -> side effect -> command complete

who requested,
when,
what operation,
which aggregate,
which previous state,
which resulting state,
which idempotency scope,
which side effects,
which reconciliation outcome.

[ ] Same key + same payload sequential retry returns same result.
[ ] Same key + different payload returns conflict.
[ ] 100 concurrent same-key attempts produce one domain effect.
[ ] Timeout after domain commit returns success/status on retry.
[ ] Timeout before domain commit retries safely.
[ ] External provider timeout enters AMBIGUOUS.
[ ] Reconciliation resolves AMBIGUOUS.
[ ] Expired key behavior matches documented contract.
[ ] Unauthorized caller cannot discover another caller's command.
[ ] Replay response does not expose sensitive data.
[ ] Duplicate in-progress returns 202/409 as contract states.
[ ] Optimistic concurrency retry with same key succeeds/replays.
[ ] New key with stale version fails 412.

int attempts = 100;
ExecutorService pool = Executors.newFixedThreadPool(20);
List<Future<Response>> futures = new ArrayList<>();

for (int i = 0; i < attempts; i++) {
    futures.add(pool.submit(() -> callCreatePayment(
        "Idempotency-Key", "same-key-123",
        Map.of("amount", 1000, "currency", "USD")
    )));
}

List<Response> responses = futures.stream().map(Future::get).toList();

assertThat(countPaymentRowsForCommand("same-key-123")).isEqualTo(1);
assertThat(countProviderCharges("same-key-123")).isEqualTo(1);
assertThat(responses).allMatch(r -> r.isSuccess() || r.isAcceptedInProgress());

POST /payments
Idempotency-Key: pay-20260706-0001
Content-Type: application/json

{
  "orderId": "ord-123",
  "amount": 125000,
  "currency": "IDR",
  "paymentMethodId": "pm-456"
}

1. API validates caller can pay order ord-123.
2. Build idempotency scope tenant+caller+CreatePayment+key.
3. Compute request hash.
4. Reserve command record.
5. Check order payable.
6. Mark payment as PENDING.
7. Write outbox PaymentChargeRequested.
8. Return 202 or 201 depending synchronous/asynchronous contract.
9. Worker calls provider using provider idempotency key.
10. Reconciliation handles provider timeout.

The API command completion and provider charge completion do not have to be the same synchronous boundary.

PATCH /cases/case-123/status
Idempotency-Key: esc-abc
If-Match: "case-version-17"

{
  "targetStatus": "ESCALATED",
  "reasonCode": "HIGH_RISK_FINDING"
}

1. Authorize case transition.
2. Reserve command key.
3. Check request hash.
4. In transaction:
   - load case with version 17,
   - validate transition REVIEWED -> ESCALATED,
   - update status,
   - increment version,
   - write audit event,
   - write outbox CaseEscalated.
5. Mark command completed.
6. Return status.

Same key + same payload -> return original success.
Different key + stale If-Match -> 412.
Same key + different targetStatus -> 409 idempotency conflict.

[ ] Every mutation endpoint has command semantics documented.
[ ] Idempotency-Key required for non-trivial command.
[ ] Idempotency scope includes tenant/caller/operation.
[ ] Request hash uses canonical semantic payload.
[ ] Same key + different hash returns conflict.
[ ] Reserve operation is atomic via unique constraint/conditional write.
[ ] Domain transaction cannot double-apply command.
[ ] Duplicate in-progress response is defined.
[ ] Duplicate completed response is defined.
[ ] Failure statuses distinguish final, retryable, and ambiguous.
[ ] External side effect has provider idempotency or side-effect record.
[ ] Timeout after commit is handled by status/replay.
[ ] TTL matches business risk.
[ ] Idempotency key is not leaked in logs unmasked.
[ ] Response replay does not expose unauthorized/sensitive data.
[ ] Metrics distinguish new, duplicate, conflict, in-progress, ambiguous.
[ ] Concurrency tests prove one side effect under 100 duplicate attempts.

API request adalah attempt.
Command adalah logical intent.
Idempotency key menghubungkan attempts ke command yang sama.
Request hash memastikan command yang sama tidak berubah makna.
Command store menyimpan lifecycle.
Database constraint/conditional write memberi atomicity.
Outbox/workflow menjaga side effect tidak hilang.
Status endpoint mengatasi unknown outcome.
Reconciliation menyelesaikan ambiguity.

Saya tahu command ini sudah pernah diterima,
saya tahu apakah payload-nya sama,
saya tahu apakah sedang diproses atau sudah selesai,
saya tahu side effect apa yang sudah terjadi,
dan saya bisa memberi caller jawaban yang aman tanpa menjalankan efek ganda.