Idempotency Key: Mendesain API yang Tahan Retry

Setiap pelanggan yang tertagih dua kali dalam sejarah punya cerita asal yang sama: client mengirim request pembayaran, jaringan timeout sebelum respons tiba, lalu seseorang atau sesuatu melakukan retry. Server memproses keduanya. Tidak ada yang menulis bug dalam arti biasa; semua pihak berperilaku wajar. Sistem secara keseluruhan tetap menarik uang dua kali, dan sekarang tim support memproses refund sementara engineering menulis postmortem.

Obatnya sudah jadi standar industri selama satu dekade: idempotency key. Client melampirkan kunci unik pada tiap operasi logis, dan server menjamin kunci tersebut dieksekusi paling banyak sekali, memutar ulang respons asli untuk setiap retry. Stripe mempopulerkan polanya, working group HTTP API di IETF menyusun draft header standarnya, dan setiap sistem yang bersinggungan dengan pembayaran yang saya bangun sejak itu memakainya. Tulisan ini membahas desain lengkapnya: semantik HTTP, storage di server, konkurensi, dan kontrak client.

Kenapa Retry Itu Keniscayaan, Bukan Pengecualian

Masalah fundamentalnya adalah kegagalan jaringan itu ambigu. Saat panggilan HTTP Anda timeout, Anda tidak bisa tahu apakah request tidak pernah sampai, sampai lalu gagal, atau sampai dan berhasil tapi responsnya hilang. Blog engineering Stripe menyebut ini masalah dua jenderal klasik dalam wujud API: client harus memilih antara tidak pernah retry, dengan risiko operasi hilang, atau retry, dengan risiko duplikat.

Praktiknya Anda bahkan tidak bisa memilih. Jaringan seluler di Indonesia memutus koneksi di tengah jalan terus-menerus; load balancer melakukan retry saat idle timeout; consumer queue mengirim ulang dengan semantik at-least-once; pengguna yang tidak sabar menekan tombol lagi. Endpoint POST mana pun yang memindahkan uang, membuat order, atau mengirim pesan cepat atau lambat akan dipanggil dua kali dengan maksud yang sama. Satu-satunya pertanyaan adalah apakah API Anda didesain untuk menyadarinya.

HTTP Sudah Menyelesaikan Setengahnya

Idempotensi sudah tertanam di sebagian besar method HTTP berdasarkan definisinya; celahnya ada di POST. Celah itu persis tempat idempotency key hidup:

Mekanika Sisi Server, Langkah demi Langkah

Implementasi yang kokoh adalah state machine kecil yang dikunci oleh idempotency key milik client. Empat langkah di bawah, beserta skemanya, adalah bentuk yang saya deploy di NestJS di atas PostgreSQL:

1. Saat request tiba, klaim kuncinya secara atomik: insert baris dengan status in_progress memakai insert-on-conflict-do-nothing sehingga tepat satu request konkuren yang memenangkan klaim.
2. Kalau insert menang, jalankan handler sungguhan di dalam transaksi database yang sama dengan penulisan bisnis Anda bila memungkinkan, lalu simpan kode dan body respons di baris kunci itu dan tandai done.
3. Kalau kunci sudah ada dan berstatus done, bandingkan hash request tersimpan dengan request yang masuk. Hash sama: putar ulang respons tersimpan apa adanya. Hash beda: tolak dengan 422, karena client memakai ulang kunci untuk operasi berbeda, yang selalu merupakan bug client yang layak dibunyikan keras-keras.
4. Kalau kunci ada tapi masih in_progress, kembalikan 409 dengan petunjuk retry-after. Jangan blokir koneksi sambil menunggu; request asli bisa makan waktu beberapa detik, dan menyandera worker mengubah badai retry menjadi outage.

-- The storage that makes it work: one row per key attempt
CREATE TABLE idempotency_keys (
  key            text PRIMARY KEY,
  request_hash   text NOT NULL,          -- sha256 of method+path+body
  response_code  int,
  response_body  jsonb,
  status         text NOT NULL DEFAULT 'in_progress',
  created_at     timestamptz NOT NULL DEFAULT now()
);

-- NestJS guard sketch (the real one is an interceptor):
-- 1. INSERT ... ON CONFLICT (key) DO NOTHING RETURNING *
-- 2. inserted?        → run the handler, store response, status='done'
-- 3. conflict + done? → compare request_hash:
--      same   → replay stored response (200, same body)
--      differs → 422: key reused for a different request
-- 4. conflict + in_progress? → 409: original still running, retry later

Pelajaran dari Implementasi Stripe

Perilaku production Stripe adalah target kalibrasi yang berguna karena sudah selamat dari trafik retry lebih banyak daripada sistem mana pun yang akan kita bangun. Kunci diterima di semua request POST, tidak diterima di GET dan DELETE karena keduanya sudah idempotent, dan disimpan setidaknya 24 jam, setelah itu kunci yang dipakai ulang diperlakukan sebagai baru. Respons yang diputar ulang mengembalikan hasil asli baik sukses maupun error, dengan header penanda idempotent-replayed supaya client bisa membedakannya.

Dua pilihan desain menonjol. Pertama, error ikut diputar ulang: kalau percobaan asli gagal validasi, retry mendapat 4xx yang sama alih-alih eksekusi kedua. Kedua, kuncinya hanyalah string opaque sampai 255 karakter, dengan rekomendasi UUID; server tidak menempelkan makna apa pun pada isinya. Kedua pilihan menjaga kontraknya cukup sederhana sehingga semua library client bisa mengimplementasikannya secara identik.

Empat Jebakan yang Sampai ke Production

Kontrak Client: Satu Kunci per Operasi, Bukan per Request

Desain server hanya berfungsi kalau client memegang separuh kontraknya: hasilkan satu kunci saat pengguna memulai operasi, lalu pakai ulang kunci yang persis sama di setiap retry operasi itu. Kunci baru per percobaan HTTP mengalahkan seluruh mekanismenya. Di frontend ERP kami kunci dibuat saat modal konfirmasi terbuka, sehingga tombol approve boleh digedor, jaringan boleh naik-turun, dan backend tetap membukukan tepat satu jurnal:

// Client side: generate ONE key per logical operation,
// reuse it across every retry of that operation.
const idempotencyKey = crypto.randomUUID()

async function createPayment(payload: PaymentDto) {
  return retryWithBackoff(() =>
    fetch("/api/payments", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Idempotency-Key": idempotencyKey, // same key on every attempt
      },
      body: JSON.stringify(payload),
    })
  )
}

Checklist Implementasi

• Terima header Idempotency-Key di setiap POST yang tidak safe; tolak request tanpa header itu di route kritis.
• Klaim kunci secara atomik dengan satu statement insert-on-conflict; jangan pernah cek-lalu-insert.
• Simpan hash request, kode respons, dan body respons; putar ulang error sama setianya dengan sukses.
• Kembalikan 409 untuk retry konkuren yang masih berjalan dan 422 untuk pemakaian ulang kunci dengan payload berbeda.
• Kedaluwarsakan kunci terjadwal, dokumentasikan jendelanya, dan kirim header penanda replay supaya client bisa mengamati deduplikasi bekerja.

Desain untuk Retry, Karena Ia Pasti Datang

Idempotency key termasuk pola dengan rasio nilai-terhadap-kode yang luar biasa: satu tabel, satu interceptor, dan satu header mengubah kelas bug distributed-systems paling menakutkan menjadi non-kejadian. Intinya, perlakukan retry sebagai kepastian beroperasi di jaringan nyata, apalagi di koneksi seluler yang dipakai mayoritas pengguna Indonesia, dan jadikan eksekusi at-most-once sebagai properti yang dijamin API Anda, bukan perilaku yang Anda harapkan. Bangun sekali, pasang di setiap POST yang penting, dan postmortem tagihan ganda menjadi cerita orang lain.