Idempotency Itu Seperti Tombol Lift: Arti Idempoten, Cara Kerja Idempotency-Key, dan Cara Mencegah Transaksi Dobel
Oleh Tim APIPedia, Tim Engineering APIPedia · Terbit · Diperbarui · 9 menit baca
Idempotency membuat request API aman diulang tanpa transaksi dobel. Ini arti idempoten, cara kerja Idempotency-Key, dan contoh kodenya.

Idempotency adalah sifat sebuah operasi yang hasil akhirnya tetap sama, entah dijalankan sekali atau berkali-kali. Cara paling gampang membayangkannya: idempotency itu seperti tombol lift. Anda boleh memencetnya lima kali karena tidak sabar, tetapi lift yang datang tetap satu. Di dunia API, sifat ini yang mencegah saldo terpotong dua kali ketika tombol "Bayar" terpencet ulang atau koneksi putus di tengah jalan.
Bagi developer dan pemilik bisnis, idempotency penting karena jaringan tidak pernah sempurna: request bisa sampai tetapi jawabannya hilang, lalu aplikasi mencoba lagi. Artikel ini membahas arti idempoten, metode HTTP mana yang aman diulang, cara kerja header Idempotency-Key, contoh kode yang sudah kami jalankan, dan hal-hal yang sering disalahpahami.
Ringkasan cepat: apa yang perlu Anda tahu?
Idempotency membuat request aman diulang, dan untuk POST caranya adalah menyertakan kunci unik yang dikenali server. Tabel berikut merangkum istilahnya.
| Istilah | Artinya |
|---|---|
| Idempoten | Efek di server sama saja, dikirim satu kali atau sepuluh kali |
| Metode aman (safe) | Metode yang hanya membaca, misalnya GET dan HEAD. Semua metode aman pasti idempoten |
| Retry | Mengirim ulang request yang sama karena timeout atau koneksi putus |
| Idempotency key | Kunci unik buatan klien, biasanya UUID acak, yang menandai satu niat transaksi |
Header Idempotency-Key | Tempat kunci itu dikirim. Masih berstatus draf standar IETF (draft-08, 22 Oktober 2026) |
| Sidik jari request (fingerprint) | Ringkasan isi request, misalnya hash, untuk memastikan satu kunci tidak dipakai untuk isi yang berbeda |
| 409 dan 422 | Kode yang disarankan draf: 409 bila request pertama masih diproses, 422 bila kunci dipakai ulang dengan isi berbeda |
Apa itu idempotency?
Idempotency adalah jaminan bahwa mengulang operasi yang sama tidak menambah efek baru. Standar HTTP (RFC 9110) mendefinisikannya begini: sebuah metode disebut idempoten bila efek yang dituju di server dari banyak request identik sama dengan efek satu request saja.
Kembali ke lift. Tombol "naik" itu idempoten: pencetan pertama membuat lampunya menyala dan lift dipanggil, pencetan kedua sampai kelima tidak mengubah apa pun. Bandingkan dengan memesan bakso lewat teriakan "Bang, satu mangkok!". Kalau Anda berteriak tiga kali karena abangnya tidak menoleh, bisa-bisa datang tiga mangkok. Teriakan itu tidak idempoten.
Supaya pesanan bakso aman diulang, Anda butuh penanda. Misalnya nomor meja: "Meja 7, satu mangkok." Abangnya mencatat, dan kalau Anda mengulang kalimat yang sama, ia cukup menjawab "Sudah dicatat, Meja 7." Nomor meja itulah peran idempotency key di API.
Kenapa request yang sama bisa terkirim dua kali?
Request terkirim dua kali karena klien sering tidak tahu apakah request pertama berhasil. Ada tiga penyebab yang paling umum:
- Jawaban hilang di jalan. Server sudah memproses pembayaran, tetapi koneksi putus sebelum jawaban sampai. Dari sisi aplikasi, ini terlihat sama persis dengan request yang gagal.
- Pengguna memencet ulang. Sinyal lemot, layar tidak berubah, tombol "Bayar" dipencet tiga kali.
- Retry otomatis. Library HTTP, antrean pesan, atau pengirim webhook mencoba ulang sendiri saat timeout.

Karena itu RFC 9110 mengingatkan: klien sebaiknya tidak mengulang otomatis request dengan metode yang tidak idempoten, kecuali ia tahu operasinya memang idempoten atau bisa memastikan request pertama tidak pernah diproses.
Metode HTTP mana yang idempoten?
Menurut RFC 9110, metode yang idempoten adalah PUT, DELETE, dan semua metode aman seperti GET, HEAD, dan OPTIONS. Dua metode yang tidak dijamin idempoten adalah POST dan PATCH.

| Metode | Idempoten? | Contoh sehari-hari |
|---|---|---|
GET, HEAD, OPTIONS | Ya, sekaligus aman | Melihat saldo. Dilihat 100 kali, saldonya tidak berubah |
PUT | Ya | Menulis ulang alamat di formulir dengan isi yang sama |
DELETE | Ya | Mencoret nama dari daftar. Dicoret lagi, tetap tercoret |
POST | Tidak dijamin | Memesan bakso tanpa nomor meja |
PATCH | Tidak dijamin | "Kurangi stok 1". Diulang tiga kali, stok berkurang tiga |
Di katalog APIPedia, sebagian besar endpoint data memakai GET, misalnya GET /v1/wilayah/provinsi atau GET /v1/kurs/latest, sehingga aman diulang saat timeout. Yang perlu perhatian ekstra adalah endpoint POST yang punya efek nyata, seperti POST /v1/sms/send yang memotong kredit SMS setiap pesan terkirim.
Bagaimana cara kerja Idempotency-Key?
Idempotency-Key bekerja dengan menitipkan satu kunci unik pada request, lalu server mengingat kunci itu beserta jawabannya. Kalau request dengan kunci yang sama datang lagi, server tidak memproses ulang dan cukup mengembalikan jawaban yang tersimpan.
- Klien membuat kunci sekali untuk satu niat transaksi, biasanya UUID acak, sebelum request pertama dikirim.
- Kunci dikirim lewat header
Idempotency-Keybersama requestPOSTatauPATCH. - Server memproses dan menyimpan kunci, sidik jari isi request, dan jawabannya.
- Saat retry, klien memakai kunci yang sama. Server mengenalinya dan memutar ulang jawaban lama.
Contoh bentuk request-nya (alamat dan token di bawah hanya ilustrasi):
curl -X POST https://api.contoh.co.id/v1/bayar \
-H "Authorization: Bearer TOKEN_ANDA" \
-H "Content-Type: application/json" \
-H 'Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"' \
-d '{"dari": "budi", "jumlah": 25000, "untuk": "warung-bu-sri"}'
Apa yang terjadi di sisi server?
Di sisi server ada lima kemungkinan, dan draf standar IETF menyarankan kode status untuk tiga kasus penolakannya.

| Kondisi | Jawaban yang disarankan draf |
|---|---|
| Kunci wajib tetapi tidak dikirim | 400 Bad Request |
| Retry datang saat request pertama masih diproses | 409 Conflict |
| Kunci dipakai ulang dengan isi request berbeda | 422 Unprocessable Content |
Contoh kode: server kecil yang idempoten
Simulasi Python berikut menunjukkan logikanya tanpa framework apa pun. Kami menjalankannya dengan Python 3 dan menyertakan keluarannya di bawah.
import hashlib, json, uuid
simpanan = {} # idempotency key -> {"sidik": ..., "status": ..., "body": ...}
saldo = {"budi": 100_000}
def sidik_jari(payload):
return hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()
def bayar(payload, key=None):
if key is None:
return 400, {"error": "Header Idempotency-Key wajib diisi"}
sidik = sidik_jari(payload)
lama = simpanan.get(key)
if lama:
if lama["sidik"] != sidik:
return 422, {"error": "Key sudah dipakai untuk isi request yang berbeda"}
if lama["status"] is None:
return 409, {"error": "Request pertama masih diproses"}
return lama["status"], lama["body"] # putar ulang jawaban lama
simpanan[key] = {"sidik": sidik, "status": None, "body": None}
saldo[payload["dari"]] -= payload["jumlah"] # efek samping terjadi SEKALI
body = {"id_transaksi": "trx_" + uuid.uuid4().hex[:8], "sisa_saldo": saldo[payload["dari"]]}
simpanan[key].update(status=201, body=body)
return 201, body
key = str(uuid.uuid4())
pesanan = {"dari": "budi", "jumlah": 25_000, "untuk": "warung-bu-sri"}
print("1.", bayar(pesanan, key)) # request pertama
print("2.", bayar(pesanan, key)) # retry setelah timeout
print("3.", bayar(pesanan, key)) # pengguna klik lagi
print("4.", bayar({**pesanan, "jumlah": 50_000}, key)) # key sama, isi beda
print("5.", bayar(pesanan)) # tanpa key
print("Saldo akhir:", saldo["budi"])
Keluaran saat kami jalankan:
1. (201, {'id_transaksi': 'trx_f4df685f', 'sisa_saldo': 75000})
2. (201, {'id_transaksi': 'trx_f4df685f', 'sisa_saldo': 75000})
3. (201, {'id_transaksi': 'trx_f4df685f', 'sisa_saldo': 75000})
4. (422, {'error': 'Key sudah dipakai untuk isi request yang berbeda'})
5. (400, {'error': 'Header Idempotency-Key wajib diisi'})
Saldo akhir: 75000
Tiga request pertama menghasilkan id_transaksi yang sama dan saldo hanya berkurang Rp25.000. Di sistem produksi, simpanan harus berupa penyimpanan bersama seperti database atau Redis dengan batas unik pada kolom kunci, karena dua request bisa tiba di dua server berbeda pada detik yang sama.
Apa yang sering disalahpahami soal idempotency?
Kesalahpahaman paling umum adalah mengira idempoten berarti jawaban server selalu sama. Yang dijamin sama adalah efek di server, bukan kode statusnya. Berikut lima hal yang perlu diluruskan.
- "Idempoten berarti responsnya identik." Tidak selalu.
DELETEpertama bisa menjawab 200, yang kedua 404 karena datanya sudah tidak ada. Efeknya tetap sama: data itu hilang. - "Idempoten sama dengan aman." Berbeda. Metode aman tidak mengubah data sama sekali.
DELETEidempoten, tetapi jelas mengubah data. - "Asal kirim header Idempotency-Key, pasti aman." Hanya kalau server mendukungnya. Header yang tidak dikenal biasanya diabaikan, dan request tetap diproses dua kali. Selalu cek dokumentasi endpoint yang Anda pakai.
- "Idempotency-Key sudah standar resmi." Belum. Statusnya masih Internet-Draft di kelompok kerja HTTPAPI IETF (draft-08 tertanggal 22 Oktober 2026, kedaluwarsa 25 April 2027 bila tidak diperbarui). Karena itu detailnya berbeda antar penyedia, misalnya panjang kunci dan lama kunci disimpan.
- "Tiap retry pakai kunci baru supaya unik." Ini justru mematikan perlindungannya. Kunci dibuat satu kali per niat transaksi dan dipakai ulang di semua percobaan. Kunci baru berarti transaksi baru.
Bagaimana tips praktis menerapkannya?
Aturan dasarnya: buat kunci sebelum request pertama, simpan, dan pakai kunci yang sama sampai Anda mendapat jawaban pasti. Rinciannya berbeda untuk sisi klien dan sisi server.
Kalau Anda memanggil API orang lain
- Buat kunci dari UUID acak, jangan dari data pribadi seperti email atau nomor telepon.
- Simpan kunci bersama data pesanan di database Anda, supaya retry setelah aplikasi restart tetap memakai kunci yang sama.
- Jangan ubah isi request saat retry. Mengubah nominal dengan kunci lama akan ditolak, dan memang seharusnya begitu.
- Perhatikan masa simpan kunci. Salah satu penyedia pembayaran besar menyebut kunci boleh dihapus setelah berumur minimal 24 jam dan panjangnya maksimal 255 karakter. Retry setelah masa itu dianggap request baru.
- Kalau endpoint tidak mendukung kunci idempotensi, cek dulu sebelum mengulang. Contohnya di SMS Gateway APIPedia: sebelum mengirim ulang
POST /v1/sms/sendyang timeout, lihat riwayat lewatGET /v1/sms/messagesuntuk memastikan pesan pertama memang belum terkirim.
Kalau Anda membangun API atau penerima webhook
- Simpan kunci dan catat efeknya dalam satu transaksi database, dengan batas unik pada kolom kunci.
- Bandingkan sidik jari isi request, dan tolak kunci yang dipakai untuk isi berbeda.
- Tentukan masa simpan kunci dan tulis di dokumentasi. Draf IETF menganjurkan kebijakan kedaluwarsa dipublikasikan.
- Penerima webhook juga harus idempoten, karena pengirim webhook biasanya mengulang kiriman saat tidak mendapat jawaban. Pakai ID event sebagai kuncinya. Penjelasan lengkapnya ada di artikel cara kerja webhook.
- Gabungkan retry dengan jeda yang makin panjang supaya tidak menabrak batas request. Lihat artikel rate limit dan error 429.
Pertanyaan yang sering diajukan
Apa bedanya idempoten dan aman (safe)?
Metode aman tidak mengubah data di server, sedangkan metode idempoten boleh mengubah data asalkan pengulangannya tidak menambah efek. Semua metode aman pasti idempoten, tetapi tidak sebaliknya: PUT dan DELETE idempoten namun tidak aman.
Apakah GET perlu Idempotency-Key?
Tidak perlu. GET sudah idempoten menurut definisi standar HTTP, jadi kunci tidak memberi manfaat apa pun. Kunci idempotensi ditujukan untuk POST dan PATCH.
Berapa lama idempotency key disimpan?
Tergantung penyedia API. Draf IETF tidak menetapkan angka dan hanya meminta kebijakan kedaluwarsa dipublikasikan. Sebagai gambaran, ada penyedia pembayaran yang menyimpan kunci minimal 24 jam.
Apa yang terjadi kalau kunci yang sama dipakai untuk isi request berbeda?
Server yang mengikuti draf IETF akan menolaknya dengan 422 Unprocessable Content. Satu kunci hanya mewakili satu isi request, jadi untuk transaksi lain Anda harus membuat kunci baru.
Apakah idempotency key sama dengan API key?
Tidak. API key menjawab "siapa yang memanggil", sedangkan idempotency key menjawab "ini request yang mana". Keduanya dikirim bersamaan lewat header yang berbeda. Soal API key, baca API key itu seperti kartu akses kos.
Untuk melanjutkan belajar konsep dasar API dan AI dengan gaya yang sama, baca juga token AI itu seperti pulsa dan beda MCP dan API biasa. Kalau ingin langsung mencoba, buat kunci di console.apipedia.id dan mulai dari endpoint GET yang aman diulang.
Sumber
Topik: #idempotency #idempotency key #api #explainer #http #retry
Tentang penulis
Tim APIPedia — Tim Engineering APIPedia
Tim engineering di balik APIPedia yang membangun dan memelihara API data Indonesia - ongkir, OCR KTP, data wilayah, BMKG, hingga server MCP - dan menulis panduan integrasinya dari pengalaman langsung.