Idempotensi & Percobaan Ulang

Setiap panggilan realtime harus membawa Idempotency-Key. Ini bukan sekadar kesopanan rate limit — inilah yang membuat percobaan ulang aman. Jaringan bisa gagal setelah pemasok sudah dimintai; tanpa key, satu-satunya cara mengetahui apakah pemeriksaan berjalan adalah menjalankannya lagi dan membayarnya dua kali.

Aturannya

Kirim nilai yang dapat Anda buat ulang: UUID, ID pesanan, atau hash dari pekerjaan yang Anda lakukan. Server membatasinya pada akun Anda, sehingga dua pengguna tidak bisa bertabrakan.

Key sama	Payload	Hasil
Key baru	apa pun	Berjalan normal, ditagih
Key sama	identik	Respons yang tersimpan dikembalikan; replayed=true. Tidak ada tagihan baru.
Key sama	berbeda	409 idempotency_conflict — sebuah key terikat pada payload yang pertama kali dibawanya
Key sama	identik, panggilan pertama masih berjalan	409 request_in_progress dengan Retry-After

Idempotency-Key dibatasi 191 byte dan catatan replay disimpan selama 30 hari secara default.

replayed bukan cached

Keduanya terlihat mirip dalam respons tetapi artinya berbeda:

Field	Di mana	Artinya
replayed	tingkat atas	Panggilan ini tidak pernah sampai ke pemasok — Anda melakukan replay atas sebuah key.
cached	di dalam tiap hasil	Putusan produk ini disajikan dari cache hasil.

Panggilan replay mereproduksi respons asli, termasuk nilai cached tiap entri. Tidak ada flag yang mengubah tagihan Anda: replay tidak pernah memindahkan uang, dan hit cache tetap ditagih dengan harga per pemeriksaan produk.

Hanya hasil yang sudah diselesaikan yang disimpan sebagai fakta. Hasil gagal dan unknown tidak di-cache — pemeriksaan berikutnya atas pengenal yang sama terhadap produk yang sama akan menanyai pemasok lagi, bukan melakukan replay atas jawaban yang tidak konklusif.

Mencoba ulang setelah kegagalan

Yang Anda lihat	Yang harus dilakukan
Timeout, atau HTTP 500	Kirim ulang body asli dengan key asli. Hasilnya tidak pasti; inilah kasus yang menjadi alasan key ini ada.
409 request_in_progress	Tunggu Retry-After, lalu kirim ulang body yang sama dengan key yang sama.
409 idempotency_conflict	Key tersebut sudah membawa payload yang berbeda. Buat key baru — jangan mengubah body lalu memakai ulang key lama.
429 realtime_rate_limited	Tunggu Retry-After. Tidak ada yang dikirim, jadi key yang sama masih belum terpakai dan aman untuk dikirim.
503 realtime_route_unavailable	Tidak ada yang dikirim. Coba lagi nanti, key yang sama.

Satu hal yang tidak boleh dilakukan setelah timeout adalah mengirim key baru untuk pekerjaan yang sama: jika panggilan pertama ternyata berhasil, Anda baru saja membayar pemeriksaan itu dua kali.

Error yang muncul di sini

HTTP	code
400	idempotency_key_required — header tidak ada
409	request_in_progress — panggilan asli masih berjalan
409	idempotency_conflict — key pertama kali dipakai dengan payload yang berbeda