Idempotency Itu Seperti Tombol Lift: Arti Idempoten, Cara Kerja Idempotency-Key, dan Cara Mencegah Transaksi Dobel

Oleh , 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.

Sampul APIPedia: judul "Idempotency: klik tiga kali, tetap satu transaksi" dengan alur tiga kartu: pembeli klik Bayar tiga kali, tiga request membawa Idempotency-Key yang sama, server mencatat 1 transaksi dan saldo terpotong sekali Rp25.000.

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.

IstilahArtinya
IdempotenEfek 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
RetryMengirim ulang request yang sama karena timeout atau koneksi putus
Idempotency keyKunci unik buatan klien, biasanya UUID acak, yang menandai satu niat transaksi
Header Idempotency-KeyTempat 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 422Kode 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.

Perbandingan dua skenario saat aplikasi kasir mengirim POST /bayar Rp25.000 lalu jawaban server hilang karena timeout. Tanpa kunci: request pertama memotong saldo Rp25.000, aplikasi mengirim ulang, server menganggapnya pesanan baru dan memotong lagi, hasilnya terpotong dua kali menjadi Rp50.000. Dengan Idempotency-Key: request pertama memotong saldo dan jawabannya disimpan, kiriman ulang dengan kunci yang sama dikenali server, jawaban lama diputar ulang, hasilnya terpotong satu kali Rp25.000.

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.

Peta metode HTTP dalam bentuk tile. Lima tile hijau: GET, HEAD, dan OPTIONS berlabel aman dan idempoten karena hanya membaca; PUT berlabel idempoten karena menimpa dengan isi yang sama; DELETE berlabel idempoten karena dihapus sekali atau tiga kali datanya tetap hilang. Dua tile kuning: POST dan PATCH berlabel tidak dijamin, karena tiap kiriman bisa membuat data baru atau menumpuk perubahan. Kartu solusi: POST dan PATCH butuh kunci idempotensi lewat header Idempotency-Key berisi UUID acak. Sumber RFC 9110 bagian 9.2.2.

MetodeIdempoten?Contoh sehari-hari
GET, HEAD, OPTIONSYa, sekaligus amanMelihat saldo. Dilihat 100 kali, saldonya tidak berubah
PUTYaMenulis ulang alamat di formulir dengan isi yang sama
DELETEYaMencoret nama dari daftar. Dicoret lagi, tetap tercoret
POSTTidak dijaminMemesan bakso tanpa nomor meja
PATCHTidak 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.

  1. Klien membuat kunci sekali untuk satu niat transaksi, biasanya UUID acak, sebelum request pertama dikirim.
  2. Kunci dikirim lewat header Idempotency-Key bersama request POST atau PATCH.
  3. Server memproses dan menyimpan kunci, sidik jari isi request, dan jawabannya.
  4. 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.

Tabel lima kemungkinan saat server menerima Idempotency-Key. Kunci belum pernah dilihat: proses request lalu simpan kunci dan jawabannya, jawaban 200 atau 201 berhasil. Kunci sama, isi sama, sudah selesai: tidak memproses ulang dan memutar ulang jawaban tersimpan. Kunci sama tetapi request pertama masih berjalan: ditolak sementara dengan 409 Conflict. Kunci sama tetapi isi request berbeda: ditolak dengan 422 Unprocessable Content. Tanpa kunci padahal endpoint mewajibkan: ditolak dengan 400 Bad Request. Sumber draf IETF Idempotency-Key header draft-08.

KondisiJawaban yang disarankan draf
Kunci wajib tetapi tidak dikirim400 Bad Request
Retry datang saat request pertama masih diproses409 Conflict
Kunci dipakai ulang dengan isi request berbeda422 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. DELETE pertama 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. DELETE idempoten, 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/send yang timeout, lihat riwayat lewat GET /v1/sms/messages untuk 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:

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.