IOSOR

IOSOR Panduan

Idempotensi API kirim: duplikat, retry, dan uang

Panduan pengembang untuk API kirim prabayar — kunci idempotensi, retry aman, pencegahan duplikat, dan korelasi ramah ledger agar kesalahan engineering tidak jadi insiden keuangan.

Timeout terjadi. Load balancer melakukan retry. Klien seluler double-tap. Tanpa idempotensi, produk "kirim sekali" jadi debit prabayar ganda dan UX OTP duplikat. Panduan ini untuk engineering dan product teknis yang mengintegrasikan API messaging prabayar white-label — setiap duplikat terlihat di dompet. IOSOR mengharapkan integrasi money-aware: panggilan terotentikasi, debit yang bisa dikorelasikan, dan error klien yang tidak menumpahkan payload merek asing. Mendekati USD 1.000+ pemakaian platform bulanan, disiplin duplikat tidak lagi opsional.

Mengapa duplikat menjadi masalah uang

Mode kegagalan Pengguna melihat Dompet melihat
Timeout klien + retry buta Dua OTP / dua peringatan Dua debit
Handler webhook non-idempoten Side effect ganda Kebingungan pada sukses
Kirim ulang pengguna di atas auto-retry Pengguna kesal Unit bertumpuk
Tanpa korelasi Tiket "gagal" Baris ledger tak cocok

Demo memaafkan. Finance produksi tidak. Pada intensitas prabayar, akhir pekan retry buta jadi proyek rekonsiliasi, bukan catatan kaki log. Rancang happy path dan jalur timeout dengan aturan debit yang sama.

Kunci idempotensi yang bertahan dari retry

Jalur kirim yang serius menerima kunci buatan klien yang unik per niat bisnis, bukan per percobaan TCP. Saat replay dalam jendela TTL, ia harus mengembalikan hasil accepted yang sama. Ini mencegah debit kedua untuk niat yang sama. Kunci harus dicatat di samping ID pesan dan referensi prabayar. Kunci ini harus bekerja melalui timeout, retry gateway, dan redrive dukungan.

Anggaran retry vs kirim ulang pengguna

Retry otomatis butuh anggaran: maks percobaan, backoff, dan kelas error mana yang boleh di-retry. Kirim ulang oleh pengguna adalah aksi produk lain dengan batas dan biaya prabayarnnya. Mencampurnya mengubah jaringan yang tidak stabil jadi peristiwa dompet akhir pekan. Ikat keduanya dengan penghentian saat saldo rendah dan alasan penolakan yang jelas.

Checklist pembeli / engineering

  1. Dokumentasi semantik kunci idempotensi dan TTL.
  2. Uji replay yang membuktikan satu debit untuk satu niat.
  3. Pemisahan anggaran auto-retry dari logika kirim ulang pengguna.
  4. Correlation ID di seluruh request, status, dan ledger.
  5. Staging yang melatih koridor nyata, bukan mock.
  6. Kebersihan kunci dan hak akses minimum untuk kredensial.
  7. Penanganan 429 dan 503 tanpa kehilangan kunci niat asli.
  8. Alert otomatis untuk tingkat penolakan kunci duplikat yang tinggi.

Bendera merah

  • "Retry sampai 200" tanpa kunci idempotensi.
  • Handler webhook non-idempoten yang memicu side effect dua kali.
  • Kunci rahasia atau token di log atau tiket support.
  • Kesalahan yang menampilkan payload merek upstream ke pengguna.
  • Tidak ada pemantauan selisih antara ledger dan jaringan.

Mulai dengan IOSOR

Di konsol kirim, tembak satu OTP atau peringatan dengan kunci idempotensi buatan klien. Paksa timeout klien, lalu putar ulang permintaan yang sama dalam TTL kunci. Buka ledger prepaid: niat itu harus menunjukkan satu debit dan satu pesan yang terlihat pengguna. Dua baris berarti kunci tidak selamat dari retry — perbaiki TTL dan handler sebelum koridor tetap Live.

Intisari IOSOR

Lakukan: anggap setiap kirim sebagai peristiwa ledger dulu. Kunci unik per niat bisnis, bukan per percobaan TCP. Auto-retry punya anggaran; ketukan kirim ulang pengguna adalah aksi produk lain dengan biaya prepaid sendiri.

Jangan: hantam sampai 200 tanpa kunci, atau biarkan webhook non-idempoten mencetak efek samping kedua. Dua OTP untuk satu ketukan adalah kutu uang, bukan cerita jaringan.

Apakah panduan ini membantu?

Panduan terkait