Siklus pengulangan tanpa seleksi sering menjadi penyebab integrasi dengan API pihak lain justru memperparah gangguan singkat, bukan melewatinya: terus-menerus memanggil dengan kunci yang sudah salah, menghabiskan batas permintaan untuk panggilan yang pasti gagal, atau, yang lebih buruk, mendebit saldo dua kali untuk pembelian yang sama. Pendekatan yang benar tidak dimulai dari jeda antarpercobaan, melainkan dari klasifikasi penyebabnya: tidak semua kesalahan layak diulang, dan tidak semua pengulangan aman.
Tiga kategori kesalahan API
Kesalahan sementara tidak berkaitan dengan isi permintaan: koneksi jaringan terputus, timeout koneksi, atau kelebihan beban sesaat pada layanan penyedia. Permintaan yang sama dengan parameter yang sama akan berjalan normal beberapa detik kemudian, karena masalahnya ada pada saluran atau waktu, bukan pada permintaannya sendiri.
Kesalahan permanen adalah kebalikannya: kunci akses salah, parameter tidak valid, atau tidak ada hak untuk operasi tersebut. Panggilan seperti ini akan gagal dengan cara yang sama pada percobaan pertama maupun keseratus, karena penyebabnya ada pada permintaan itu sendiri atau pengaturan akun. Mengulang tanpa memperbaiki penyebabnya tidak menghasilkan apa pun selain satu baris tambahan di log.
Kesalahan terkait uang secara bentuk mirip dengan kesalahan sementara: saldo tidak cukup, atau tidak ada nomor yang tersedia untuk negara yang diminta. Permintaan ulang mungkin berhasil nanti, setelah saldo diisi atau stok diperbarui, tetapi tidak boleh diulang secara membabi buta, apalagi operasi pendebitan itu sendiri. Bagian-bagian berikut menjelaskan alasannya.
Apa yang diulang dan apa yang tidak
Aturannya sederhana: yang layak diulang hanyalah yang bisa pulih sendiri seiring waktu. Gangguan jaringan, timeout, respons 5xx, atau tanda kelebihan beban adalah kandidat untuk pengulangan otomatis dengan skema backoff. Kunci yang salah, parameter yang tidak benar, atau penolakan karena hak akses tidak ada gunanya diulang selama penyebabnya belum diatasi secara manual: perbaiki pengaturannya, lalu kirim ulang panggilan satu kali, bukan menjalankan siklus berulang. Kekurangan saldo atau stok ditampilkan kepada pihak pemanggil sebagai status tersendiri, dan keputusan untuk mengulang diambil oleh logika bisnis atau pengguna, bukan oleh timer. Di bagian mana dalam model "pembelian sekali pakai atau sewa berjangka" kekurangan stok lebih sering terjadi, dibahas dalam artikel aktivasi OTP vs sewa nomor.
Exponential backoff dan harga dari pengulangan buta
Exponential backoff adalah jeda sebelum percobaan berikutnya yang bertambah panjang setiap kali: misalnya satu detik, lalu dua, empat, delapan, hingga batas beberapa percobaan, biasanya tiga sampai lima, setelah itu siklus dihentikan dan kegagalan diteruskan ke tingkat yang lebih atas sebagai hasil akhir. Pada jeda ini sebaiknya ditambahkan sedikit variasi acak, agar banyak klien yang menghadapi gangguan penyedia yang sama tidak menyerangnya secara serempak tepat saat layanan pulih.
Tanpa klasifikasi di awal, backoff tidak menolong: bila diterapkan pada penyebab permanen, backoff hanya memperpanjang waktu panggilan yang sia-sia, dan setiap panggilan itu menempati satu slot dalam batas umum akun. Selama siklus terus memanggil dengan kunci yang tidak valid, permintaan berguna dari akun yang sama, yaitu aktivasi nyata dan pemeriksaan status, terbentur batas yang sama dan ditolak karena pembatasan kecepatan. Pada otomatisasi dengan worker paralel, seperti dibahas dalam artikel tentang pendaftaran melalui API, satu proses yang terjebak dalam siklus pengulangan dapat menghabiskan batas untuk semua proses lainnya.
Log untuk analisis insiden
Setelah gangguan, analisis dilakukan berdasarkan log, bukan ingatan, sehingga yang dicatat harus cukup untuk menjawab pertanyaan "ini masalah penyedia atau di pihak kita" tanpa harus mereproduksi masalahnya lagi. Set minimum: waktu panggilan, endpoint, pengenal permintaan atau aktivasi, kode dan teks penolakan dari penyedia, nomor urut percobaan, serta parameter tanpa data rahasia, karena kunci dan token tidak boleh masuk ke log.
Secara terpisah, sebaiknya dicatat bukan hanya respons penyedia, tetapi juga bagaimana pengendali Anda mengklasifikasikan penyebabnya, apakah sebagai sementara, permanen, atau terkait uang. Jika pengklasifikasi keliru dan penyebab permanen ternyata diulang seolah-olah sementara, hal itu hanya terlihat dari catatan semacam ini, bukan dari kode respons saja.
Idempotensi operasi uang: cara agar tidak mendebit dua kali
Timeout tidak menjelaskan dengan pasti apakah operasi sudah dijalankan di server atau belum: koneksi bisa saja terputus setelah pendebitan, tetapi sebelum respons sampai ke klien. Mengulang permintaan seperti itu tanpa perlindungan akan tampak bagi API sebagai operasi baru, dan berujung pada pendebitan ganda untuk pembelian yang sama.
Kunci idempotensi menyelesaikan masalah ini: klien membuat satu pengenal unik per operasi, lalu menyertakannya pada setiap percobaan, termasuk pengulangan setelah timeout. Server mengingat hasil yang diberikan untuk kunci tersebut, dan saat ada permintaan ulang dengan nilai yang sama, server mengembalikan hasil itu alih-alih menjalankan operasi lagi. Ini satu-satunya cara aman untuk mengulang panggilan terkait uang: tanpa kunci, risiko pendebitan ganda selalu ada.
Pertanyaan yang Sering Diajukan
Apakah kesalahan 429 perlu diulang seperti timeout?
Ya, tetapi dengan jeda yang lebih panjang: 429 bukan berarti gangguan, melainkan batas permintaan yang sudah habis, dan pengulangan seketika hanya memperpanjang waktu tunggu bagi semua pihak. Gunakan nilai dari header respons jika penyedia menyediakannya, atau mulai backoff langsung dengan jeda beberapa detik, bukan satu detik.
Bolehkah permintaan pendebitan saldo diulang otomatis saat timeout?
Bukan permintaannya sendiri, melainkan hanya operasi dengan kunci idempotensi. Timeout tidak menjelaskan apakah operasi sudah dijalankan di server sebelum koneksi terputus; mengulang dengan kunci yang sama aman karena penyedia akan mengembalikan hasil operasi yang sudah dijalankan alih-alih mendebit lagi. Tanpa kunci, pengulangan seperti ini berisiko menggandakan pembayaran.
Berapa banyak percobaan yang wajar untuk mengulang kesalahan sementara?
Umumnya tiga sampai lima percobaan dengan jeda eksponensial dan batas total waktu tunggu sekitar 30-60 detik. Percobaan yang lebih banyak jarang mengubah hasilnya: jika penyedia belum pulih dalam rentang waktu ini, masalahnya bersifat sistemik dan sebaiknya dieskalasi, bukan terus diulang dalam siklus.
Kode berdasarkan kategori, header kunci idempotensi, dan parameter pengulangan untuk setiap endpoint ada di dokumentasi API. Penerimaan peristiwa melalui webhook, yang juga bergantung pada pengulangan dan idempotensi, dibahas dalam artikel webhook: menerima kode tanpa polling, sedangkan skenario dasar integrasi ada dalam materi API sewa nomor.