Penanganan kesalahan lanjutan

Halaman ini membahas dua topik penanganan kesalahan lanjutan:

• Respons HTTP yang mewakili kesalahan
• Idempotensi dan coba ulang

Informasi ini mungkin tidak berlaku untuk Anda. SDK resmi Stripe dapat menangani sebagian besar detail yang melibatkan HTTP dan coba ulang. Jika Anda menggunakan pustaka client, mulai di sini:

• Penanganan kesalahan
• Kode kesalahan

Kesalahan di HTTP

Bahkan ketika panggilan API gagal, pustaka client kami menyediakan informasi kesalahan dengan mengajukan pengecualian atau mengembalikan nilai kesalahan. Namun, jika Anda tidak menggunakan pustaka client, atau jika situasi yang tidak biasa muncul, Anda mungkin membutuhkan detail tingkat rendah tentang respons HTTP dan kapan kami mengeluarkannya.

Dari sudut pandang HTTP, kesalahan terbagi dalam tiga kategori utama:

• Kesalahan konten: Konten tidak valid dalam permintaan API.
• Kesalahan jaringan: Masalah komunikasi sesekali antara client dan server.
• Kesalahan server: Ada masalah pada server Stripe.

Setiap tipe kesalahan memerlukan pendekatan serta semantik idempotensi yang berbeda. Pencantuman lengkap kode respons dan artinya disediakan pada akhir halaman ini.

Kesalahan konten

Kesalahan konten diakibatkan oleh konten yang tidak valid dari permintaan API. Respons HTTP dikembalikan dengan kode respons 4xx. Misalnya, server API mungkin mengembalikan 401 jika Anda memberikan kunci API yang tidak valid, atau 400 jika parameter yang diperlukan tidak ada. Integrasi harus mengoreksi permintaan semula, dan coba lagi. Tergantung tipe kesalahan pengguna (misalnya, kartu ditolak), bisa jadi hal ini untuk menangani masalah secara terprogram. Dalam kasus ini, sertakan bidang code untuk membantu integrasi bereaksi dengan tepat. Lihat kode kesalahan untuk detail selengkapnya.

Untuk operasi POST menggunakan kunci idempotensi, selama metode API mulai dilaksanakan, server API Stripe akan meng-cache hasil permintaan apa pun hasilnya. Permintaan yang mengembalikan 400 mengirimkan kembali 400 yang sama jika diikuti oleh permintaan baru dengan kunci idempotensi yang sama. Buat kunci idempotensi baru ketika mengubah permintaan semula untuk mendapatkan hasil yang sukses. Operasi ini memang berisi beberapa peringatan. Misalnya, permintaan yang tingkatnya dibatasi dengan 429 dapat membuahkan hasil yang berbeda dengan kunci idempotensi yang sama karena pembatas tingkat dijalankan sebelum lapisan idempotensi API. Hal yang sama berlaku untuk 401 yang menghilangkan kunci API, atau sebagian besar 400 yang mengirim parameter tidak valid. Meski begitu, strategi paling aman terkait kesalahan 4xx adalah selalu membuat kunci idempotensi baru.

Kesalahan jaringan

Kesalahan jaringan adalah hasil dari masalah konektivitas antara client dan server. Kesalahan tingkat rendah, seperti pengecualian soket atau batas waktu, dikembalikan. Misalnya, client mungkin waktunya habis saat mencoba membaca dari server Stripe, atau respons API mungkin tidak pernah dapat diterima karena koneksi berakhir sebelum waktunya. Walaupun kesalahan jaringan seperti itu tampaknya akan berhasil setelah Anda memperbaiki masalah konektivitas, terkadang ada tipe kesalahan lain yang bersembunyi dalam masalah yang sesekali terjadi.

Kelas kesalahan ini merupakan tempat nilai kunci idempotensi dan coba ulang permintaan paling jelas terlihat. Jika ada masalah yang sesekali terjadi, client biasanya berada dalam status di mana mereka tidak mengetahui apakah server menerima permintaan atau tidak. Untuk mendapatkan jawaban pasti, mereka harus mencoba ulang permintaan tersebut dengan kunci idempotensi dan parameter yang sama hingga mereka dapat menerima hasil dari server. Pengiriman idempotensi yang sama dengan parameter yang berbeda menghasilkan kesalahan yang merupakan indikasi permintaan baru tidak sama dengan yang semula.

Kebanyakan pustaka client dapat menghasilkan kunci idempotensi dan mencoba ulang permintaan secara otomatis, tetapi perlu dikonfigurasi untuk melakukannya. Pustaka tersebut melakukan coba ulang pertama dengan cepat setelah kegagalan pertama, dan coba ulang selanjutnya pada jadwal backoff eksponensial, dengan asumsi bahwa satu kegagalan sering kali merupakan kejadian acak, tetapi pola kegagalan berulang kemungkinan besar merupakan masalah kronis.

Stripe.max_network_retries = 2

Kesalahan server

Kesalahan server merupakan akibat dari masalah dengan server Stripe. Respons HTTP dikembalikan dengan kode kesalahan 5xx. Kesalahan ini merupakan yang paling sulit ditangani dan kami berupaya membuatnya seminim mungkin terjadi, tetapi integrasi yang baik akan menanganinya bila muncul.

Seperti kesalahan pengguna, lapisan idempotensi meng-cache hasil mutasi POST yang mengakibatkan kesalahan server (khususnya 500, yang merupakan kesalahan server internal), jadi pencobaan ulang dengan kunci idempotensi yang sama biasanya membuahkan hasil yang sama. Client dapat mencoba ulang permintaan dengan kunci idempotensi baru, tetapi kami menyarankan untuk tidak melakukannya karena kunci semula mungkin telah menghasilkan efek samping.

Anda harus memperlakukan hasil permintaan 500 sebagai tidak tentu. Waktu yang paling mungkin untuk mengamati seseorang adalah selama insiden produksi, dan umumnya selama remediasi insiden semacam itu. Teknisi Stripe memeriksa permintaan yang gagal dan mencoba untuk merekonsiliasi dengan tepat hasil mutasi yang menghasilkan 500. Walaupun respons cache idempotensi terhadap permintaan tersebut tidak akan berubah, kami akan mencoba mengaktifkan webhook untuk objek baru yang dibuat sebagai bagian dari rekonsiliasi Stripe. Sifat pasti dari setiap perubahan retroaktif dalam sistem sangat bergantung pada jenis permintaan. Misalnya, jika membuat charge mengembalikan kesalahan 500 tetapi kami mendeteksi bahwa informasi tersebut telah masuk ke jaringan pembayaran, kami akan mencoba untuk memajukannya. Jika tidak, kami akan mencoba memutarnya kembali. Jika ini tidak menyelesaikan masalah, Anda mungkin masih melihat permintaan dengan kesalahan 500 yang menghasilkan efek samping yang terlihat pengguna.

Agar integrasi Anda dapat menangani rentang terluas 500, konfigurasikan handler webhook untuk menerima objek kejadian yang tidak pernah Anda terima dalam respons API normal. Salah satu teknik untuk mereferensikan silang objek baru ini dengan data dari status lokal integrasi adalah mengirimkan pengidentifikasi lokal dengan metadata ketika membuat sumber daya baru dengan API. Pengidentifikasi tersebut muncul di bidang metadata dari objek yang keluar melalui webhook, sekalipun webhook tersebut dibuat di lain waktu sebagai bagian dari rekonsiliasi.

Idempotensi

Idempotensi adalah prinsip desain API web yang didefinisikan sebagai kemampuan untuk menerapkan operasi yang sama beberapa kali tanpa mengubah hasil di luar percobaan pertama. Aman untuk mencoba ulang permintaan API dalam beberapa situasi—khususnya, bila permintaan pertama tidak mendapat respons karena kesalahan jaringan. Karena diperkirakan adanya sejumlah kegagalan sesekali, client membutuhkan cara untuk melakukan rekonsiliasi permintaan yang gagal dengan server, dan idempotensi menyediakan mekanisme untuk itu.

Kebanyakan pustaka client dapat menghasilkan kunci idempotensi dan mencoba ulang permintaan secara otomatis, tetapi Anda perlu mengonfigurasinya. Untuk kontrol yang lebih akurat atas coba ulang, buat kunci idempotensi dan tulis logika Anda sendiri untuk coba ulang.

Permintaan GET dan DELETE

Stripe API menjamin idempotensi permintaan GET dan DELETE, jadi selalu aman untuk mencobanya ulang.

Permintaan POST

Menyertakan kunci idempotensi membuat permintaan POST menjadi idempoten, yang meminta API melakukan penyimpanan catatan yang diperlukan untuk mencegah operasi duplikat. Client dapat mencoba ulang permintaan yang menyertakan kunci idempotensi dengan aman selama permintaan kedua terjadi dalam waktu 24 jam sejak Anda pertama kali menerima kunci (kunci kedaluwarsa dari sistem setelah 24 jam). Misalnya, jika permintaan untuk membuat objek tidak merespons karena kesalahan koneksi jaringan, client dapat mencoba ulang permintaan dengan kunci idempotensi yang sama untuk menjamin bahwa tidak lebih dari satu objek dibuat.

Mengirim kunci idempotensi

Kunci idempotensi dikirim di header Idempotency-Key. Gunakan untuk semua permintaan POST ke Stripe API. Sebagian besar pustaka client resmi dapat mengirimnya secara otomatis, selama dikonfigurasi untuk mengirim percobaan ulang.

Jika Anda memutuskan untuk mengirim kunci idempotensi secara manual, pastikan token yang digunakan cukup unik untuk mengidentifikasi dengan tepat satu operasi dalam akun Anda minimal selama 24 jam terakhir. Ada dua strategi umum untuk membuat kunci idempotensi:

• Gunakan algoritma yang menghasilkan token yang cukup acak, seperti UUID v4.
• Dapatkan kunci dari objek yang dilampirkan pengguna, seperti identifikasi keranjang belanja. Hal ini memberikan cara yang relatif mudah untuk memberikan proteksi terhadap penyerahan ganda.

Untuk mengidentifikasi respons yang dilaksanakan sebelumnya yang sedang diputar ulang dari server, cari header Idempotent-Replayed: true.

Header Stripe-Should-Retry

Pustaka client tidak selalu dapat menentukan dengan pasti apakah harus mencoba ulang hanya berdasarkan kode status atau konten di isi respons saja. API merespons dengan header Stripe-Should-Retry bila memiliki informasi tambahan bahwa permintaan dapat dicoba ulang.

• Stripe-Should-Retry yang diatur ke true menunjukkan bahwa client harus mencoba ulang permintaan. Client masih harus menunggu beberapa waktu (mungkin ditentukan menurut jadwal backoff eksponensial) sebelum membuat permintaan berikutnya agar tidak membebani API.
• Stripe-Should-Retry yang diatur ke false berarti client tidak seharusnya mencoba ulang permintaan karena tidak akan memiliki efek tambahan.
• Stripe-Should-Retry yang tidak diatur di respons mengindikasikan bahwa API tidak dapat menentukan apakah dapat mencoba ulang permintaan atau tidak. Client harus mundur kembali ke properti lain dari respons (seperti kode status) untuk membuat keputusan.

Mekanisme coba ulang yang dibangun ke dalam pustaka client Stripe mengikuti Stripe-Should-Retry secara otomatis. Jika menggunakan salah satunya, Anda tidak perlu menanganinya secara manual.

Referensi Kode Status HTTP