Digital Transformation
Idempotency Key
TL;DR: Idempotency Key adalah token unik yang disertakan dalam request API supaya server tahu request yang sudah pernah diproses tidak boleh dieksekusi ulang. Pola ini wajib di sistem pembayaran, booking, dan event kritis lain. Tanpa idempotency, retry otomatis dari klien bisa berujung double-charge atau duplikasi pesanan.
Apa itu Idempotency Key?
Idempotency artinya operasi yang dipanggil berkali-kali memberi hasil yang sama dengan satu kali panggilan. Dalam praktik HTTP, klien yang mengalami timeout sering mengulang request. Tanpa proteksi, server bisa membuat dua transaksi yang sebenarnya satu maksud. Idempotency Key memecahkan ini dengan cara klien menghasilkan UUID unik per intent, lalu mengirimnya di header Idempotency-Key. Server menyimpan respons pertama dan mengembalikannya untuk request berikutnya dengan key yang sama.
Pola ini dipakai oleh Stripe, Midtrans, dan banyak gateway pembayaran. Erat hubungannya dengan rate limiting dan webhook karena ketiganya berbagi tema reliability.
Cara Implementasi
| Komponen | Tanggung jawab |
|---|---|
| Klien | Buat UUID v4 per intent, simpan sampai konfirmasi sukses |
| Header | Kirim Idempotency-Key: <uuid> di setiap retry |
| Server | Cache respons pertama selama TTL (24 jam standar) |
| Storage | Tabel idempotency_records dengan key, response_body, status_code, created_at |
Window TTL umumnya 24 jam. Stripe pakai 24 jam, Midtrans pakai window yang lebih panjang untuk transaksi tertentu.
Kenapa Penting?
Untuk e-commerce Indonesia yang banyak terbantu retry mekanisme di payment gateway, ketiadaan idempotency menjadi penyebab umum keluhan double-charge. Berdasarkan praktik standar industri, setiap endpoint yang sifatnya state-mutating dan kritis (POST/PUT untuk pembayaran, booking, transfer) wajib mendukung header ini. Spesifikasi formalnya didokumentasikan di draft IETF tentang Idempotency-Key.
Marketer mungkin tidak menulis kode, tapi perlu memahami konsep ini saat mendesain UX checkout. Tombol bayar yang bisa diklik dua kali tanpa idempotency adalah resep keluhan pelanggan.
Pertanyaan Umum
Apakah idempotency sama dengan retry?
Tidak. Retry adalah strategi klien. Idempotency adalah jaminan server bahwa retry aman.
Berapa panjang TTL yang ideal?
24 jam adalah standar de facto. Cukup panjang untuk menutup kasus retry dan tidak terlalu boros storage.
Apa yang terjadi jika klien lupa kirim key?
Server memperlakukan request seperti baru. Setiap eksekusi akan jalan dan berpotensi duplikasi. Itu sebabnya tanggung jawab key ada di klien.
Istilah Terkait