Idempotency

Cara Menggunakan

POST /v1/chart HTTP/1.1
X-Api-Key: aw_live_...
Idempotency-Key: 01HXY2A7ZM0ABCDEF
Content-Type: application/json

{ "datetime": "1990-07-14T14:30:00", ... }

Idempotency-Key - string sembarang hingga 64 karakter, unik untuk setiap operasi logis. Direkomendasikan - ULID atau UUID v4.

Jaminan

• Selama 24 jam setelah permintaan pertama dengan kunci ini, permintaan berulang dengan kunci yang sama akan mengembalikan respons yang sama tanpa perhitungan ulang dan tanpa mengurangi kredit.
• Jika body permintaan berbeda dengan aslinya: mengembalikan 409 Conflict dengan kode idempotency_key_reuse.
• Setelah 24 jam kunci akan dilupakan, permintaan baru dengan kunci yang sama akan menjadi permintaan biasa.

Catatan

Idempotensi adalah perlindungan terhadap penagihan ganda saat terjadi kegagalan jaringan, bukan caching. Untuk caching, gunakan mekanisme X-Cache yang alami (5 menit, lihat Kredit dan Batasan).

Kapan Diperlukan

• Di webhook-handler, di mana retry datang dari sistem eksternal (misalnya, payment provider atau CRM mengirimkan event yang kamu parse dan lakukan perhitungan)
• Di background job, di mana retry: perilaku standar saat terjadi kegagalan
• Di CI/CD pipeline, di mana test bisa dijalankan ulang

Untuk interaksi normal “pengguna klik tombol → menampilkan peta” idempotensi tidak diperlukan - pengguna tetap akan melihat hasilnya, biasanya tidak ada klik berulang.

Kapan Tidak Menggunakan

• Jangan set kunci untuk menghemat kredit pada permintaan yang identik: untuk ini ada X-Cache (gratis, 5 menit)
• Jangan generate kunci dari hash(body): maka kamu akan kehilangan perilaku default Idempotency-Key (409 berulang saat body tidak cocok)