Kunci Idempotensi, Secara Praktis

Retry bukanlah kasus tepi — itu perilaku default setiap jaringan. Pertanyaannya bukan apakah sebuah request tiba dua kali, melainkan kapan.

Kontrak minimum yang layak

Klien membuat sebuah kunci (UUID sudah cukup) dan mengirimnya bersama request tulis:

POST /payments
Idempotency-Key: 5f9c...e21

Server menyimpan kunci itu sebelum mengerjakan tugas, dibatasi per endpoint dan per pemanggil. Tiga kemungkinan:

1. Kunci baru → proses, simpan respons terhadap kunci, kembalikan.
2. Kunci sedang berjalan → kembalikan 409 dan biarkan klien menunggu.
3. Kunci selesai → putar ulang respons tersimpan apa adanya. Tanpa eksekusi ulang.

Yang sering keliru

• Mem-hash isi request alih-alih memakai kunci dari klien — kini “request sama, niat baru” yang sah malah tertelan diam-diam.
• Menyimpan kunci setelah efek samping terjadi, menyisakan celah saat crash.
• Lupa TTL, sehingga tabel kunci tumbuh selamanya.

Idempotensi adalah properti yang Anda rancang ke dalam operasi tulis, bukan middleware yang ditambahkan belakangan.