Batas tingkat

Stripe API menggunakan sejumlah pengamanan terhadap semburan lalu lintas yang masuk guna membantu memaksimalkan stabilitasnya. Jika Anda mengirim banyak permintaan secara berurutan dalam rentang waktu pendek, Anda mungkin melihat respons kesalahan dengan kode status 429.

Pembatas API

Kami memiliki beberapa pembatas di API, termasuk pembatas laju dan pembatas konkurensi.

Perlakukan batas ini sebagai maksimum, dan jangan buat beban yang tidak perlu. Untuk mencegah penyalahgunaan, kami mungkin mengurangi batasnya.

Untuk mendapat saran tentang penanganan kesalahan 429, lihat Penanganan pembatasan dengan baik. Jika Anda tiba-tiba melihat lonjakan jumlah permintaan yang diberi laju terbatas, hubungi Dukungan Stripe.

Anda dapat meminta peningkatan batas untuk mengaktifkan aplikasi lalu lintas tinggi dengan menghubungi Dukungan Stripe. Jika Anda meminta peningkatan yang besar, hubungi kami minimal 6 minggu sebelumnya.

Pembatas laju

Pembatas laju dasar membatasi jumlah permintaan API per detik sebagai berikut:

• Mode live: 100 operasi
• Sandbox: 25 operasi

Panggilan ke masing-masing sumber daya memiliki batas yang lebih ketat, dan juga dihitung terhadap batas global. Endpoint API memiliki batas default 25 permintaan per detik. Stripe dapat meningkatkan batas kecepatan untuk akun spesifik berdasarkan penggunaan.

• Files API: 20 operasi baca dan 20 operasi tulis per detik
• Search API: 20 operasi baca per detik

Panggilan ke endpoint kejadian Meter dalam mode live tunduk pada batas kecepatan terpisah, dan tidak dihitung terhadap batas dasar. Batasnya adalah 1000 panggilan per detik per akun Stripe. Di sandbox, panggilan ke endpoint peristiwa Meter dihitung terhadap batas dasar. Untuk platform Connect, panggilan pada akun terhubung ke endpoint kejadian Meter juga dihitung terhadap batas dasar.

Permintaan dengan batas kecepatan

Permintaan yang dibatasi kecepatannya mengembalikan header Stripe-Rate-Limited-Reason dengan nilai yang menunjukkan batas kecepatan mana yang permintaannya terlampaui. Nilai yang mungkin untuk header ini adalah:

• global-concurrency: Permintaan Anda telah melampaui batas konkurensi global. Anda dapat mencegah hal ini dengan mengirimkan lebih sedikit permintaan secara bersamaan.
• global-rate: Permintaan Anda telah melampaui batas kecepatan global. Anda dapat mencegah hal ini dengan mengirimkan permintaan pada kecepatan yang lebih rendah.
• endpoint-concurrency: Permintaan Anda untuk endpoint API spesifik ini telah melampaui batas konkurensi. Anda dapat mencegah hal ini dengan mengirimkan lebih sedikit permintaan secara bersamaan ke endpoint spesifik ini.
• endpoint-rate: Permintaan Anda ke endpoint API spesifik ini telah melampaui batas kecepatan. Anda dapat mencegah hal ini dengan mengirimkan permintaan ke endpoint ini pada kecepatan yang lebih rendah.
• resource-specific: Anda telah mencapai batas kecepatan yang terkait dengan sumber daya API spesifik. Lihat dokumentasi sumber daya tersebut untuk informasi selengkapnya.

Jika permintaan mengembalikan kode status 429 tanpa header ini, itu bukan hasil pembatas kecepatan (misalnya, itu mungkin waktu penguncian habis).

Pembatas konkurensi

Pembatas konkurensi membatasi jumlah permintaan aktif serentak. Masalah dengan pembatas ini kurang umum dibandingkan dengan pembatas laju, tetapi kemungkinan menunjukkan adanya permintaan berumur panjang yang intensif sumber daya.

Panggilan ke Endpoint kejadian meter terbatas pada satu panggilan serentak per pelanggan per meter.

Penyebab dan mitigasi umum

Pembatasan kecepatan dapat terjadi dalam berbagai kondisi, tetapi yang paling umum terjadi dalam skenario ini:

• Menjalankan permintaan berjarak dekat dalam volume besar dapat menyebabkan pembatasan tingkat. Hal ini sering kali merupakan bagian dari operasi analitis atau migrasi. Ketika terlibat dalam aktivitas ini, Anda harus mencoba mengontrol tingkat permintaan pada sisi client (lihat Penanganan pembatasan dengan baik).
• Penerbitan banyak permintaan berumur panjang dapat memicu pembatasan. Permintaan bervariasi dalam hal jumlah sumber daya server Stripe yang digunakan, dan permintaan yang lebih intensif sumber daya cenderung membutuhkan waktu lebih lama serta berisiko menyebabkan permintaan baru dibatasi oleh pembatas konkurensi. Persyaratan sumber daya sangat bervariasi, tetapi permintaan daftar dan permintaan yang menyertakan perluasan biasanya menggunakan lebih banyak sumber daya dan membutuhkan waktu lebih lama untuk dijalankan. Kami menyarankan pembuatan profil durasi permintaan Stripe API serta pemerhatian batas waktu untuk mencoba dan menemukan waktu yang lambat secara tak terduga.
• Peningkatan tiba-tiba dalam volume charge seperti penjualan kilat mungkin mengakibatkan pembatasan laju. Kami mencoba mengatur laju kami cukup tinggi sehingga lalu lintas pembayaran yang sah tidak pernah melebihi batas, tetapi jika Anda menduga kejadian mendatang mungkin menyebabkan batas yang tercantum di atas terlampaui, hubungilah Dukungan Stripe.

Penanganan pembatasan dengan baik

Teknik dasar integrasi agar dapat menangani pembatasan dengan baik adalah memperhatikan kode status 429 dan membuat mekanisme coba ulang. Mekanisme coba ulang harus mengikuti jadwal backoff eksponensial untuk mengurangi volume permintaan bila perlu. Kami juga merekomendasikan pembuatan beberapa hal acak ke jadwal backoff guna menghindari efek thundering herd.

Anda hanya dapat mengoptimalkan permintaan perorangan hingga tingkat tertentu, jadi pendekatan yang lebih canggih adalah mengontrol lalu lintas kunjungan ke Stripe di tingkat global, dan membatasinya kembali jika Anda mendeteksi pembatasan tingkat yang substansial. Teknik umum untuk mengontrol tingkat adalah mengimplementasikan sesuatu seperti algoritma pembatasan tingkat wadah token pada sisi client. Implementasi siap-pakai dan matang untuk wadah token tersedia di hampir semua bahasa pemrograman.

Batas waktu penguncian objek

Integrasi mungkin mengalami kesalahan dengan status HTTP 429, kode lock_timeout, dan pesan ini:

Objek ini sekarang tidak dapat diakses karena permintaan API atau proses Stripe lain tengah mengaksesnya. Jika Anda melihat kesalahan ini hanya sesekali, coba ulang permintaan. Jika Anda sering melihat kesalahan ini dan sedang membuat beberapa permintaan serentak ke satu objek, buat permintaan secara berseri atau dengan kecepatan yang lebih rendah.

Stripe API mengunci objek pada beberapa operasi sehingga beban kerja serentak tidak mengganggu serta memberikan hasil yang tidak konsisten. Kesalahan di atas disebabkan oleh permintaan yang mencoba memperoleh penguncian yang sudah dilakukan di tempat lain, dan waktunya habis setelah tidak dapat diperoleh tepat pada waktunya.

Batas waktu penguncian memiliki penyebab yang berbeda dengan pembatasan laju, tetapi mitigasinya serupa. Seperti halnya kesalahan pembatasan laju, kami merekomendasikan coba ulang pada jadwal backoff eksponensial (lihat Penanganan pembatasan dengan baik). Namun, tak seperti kesalahan pembatasan laju, mekanisme coba ulang otomatis yang dibangun ke SDK Stripe mencoba ulang 429 yang disebabkan oleh batas waktu penguncian:

Stripe.max_network_retries = 2

Ketidakcocokan penguncian disebabkan oleh akses serentak pada objek yang dikaitkan. Integrasi dapat sangat mengurangi hal ini dengan memastikan bahwa mutasi pada objek yang sama dimasukkan ke dalam antrean dan sebagai gantinya dijalankan secara berurutan. Operasi serentak terhadap API masih tidak masalah, tetapi coba pastikan operasi simultan hanya beroperasi pada objek yang unik. Juga memungkinkan untuk melihat ketidakcocokan penguncian yang disebabkan oleh pertentangan dengan proses latar belakang Stripe internal—hal ini seharusnya jarang terjadi, tetapi karena berada di luar kendali pengguna, kami merekomendasikan semua integrasi dapat mencoba ulang permintaan.

Percobaan beban

Sudah umum bagi pengguna untuk mempersiapkan acara penjualan besar dengan menguji beban sistem, dengan API Stripe berjalan di sandbox sebagai bagian darinya. Kami umumnya tidak menganjurkan praktik ini karena batas API lebih rendah di sandbox, sehingga uji beban kemungkinan akan mencapai batas yang tidak akan tercapai dalam produksi. Sandbox juga bukan pengganti yang sempurna untuk panggilan API langsung, dan itu bisa agak menyesatkan. Misalnya, membuat charge dalam mode live mengirim permintaan ke gateway pembayaran dan permintaan tersebut dijadikan rekaan di sandbox, sehingga menghasilkan profil latensi yang sangat berbeda.

Sebagai alternatif, kami merekomendasikan pembuatan integrasi agar memiliki sistem yang dapat dikonfigurasi untuk membuat rekaan permintaan ke Stripe API, yang dapat Anda aktifkan untuk percobaan beban. Untuk hasil yang realistis, integrasi harus menyimulasikan latensi dengan tidur selama waktu yang Anda tentukan dengan mengambil sampel durasi panggilan API Stripe mode live nyata, seperti yang terlihat dari perspektif integrasi.

Alokasi permintaan baca API

Stripe menyediakan akses ke permintaan API (GET) baca untuk memfasilitasi aktivitas pencarian sewajarnya yang terkait dengan integrasi pembayaran. Guna memaksimalkan kualitas layanan bagi semua pengguna, Stripe menyediakan alokasi berikut untuk permintaan baca berdasarkan jumlah transaksi:

• Permintaan API baca tidak boleh melebihi rasio rata-rata 500 permintaan per transaksi untuk sebuah akun. Misalnya, jika akun memproses 100 transaksi dalam periode 30 hari, maka tidak boleh melebihi 50.000 permintaan API baca selama periode yang sama.
• Saat menggunakan Connect, platform dan akun terhubungnya memiliki izin API baca yang berbeda:
  • Setiap akun terhubung memiliki alokasi masing-masing untuk permintaan yang diprakarsai (500 permintaan per transaksi).
  • Platform Connect menggunakan alokasi terpisah untuk membuat permintaan baca atas nama akun terhubung menggunakan kunci API rahasianya atau token akses OAuth. Alokasi ini juga berjumlah 500 permintaan per transaksi berdasarkan hitungan transaksi agregat di seluruh akun terhubung.
• Rasio diukur setiap 30 hari.
• Setiap akun, berapa pun hitungan transaksinya, memiliki alokasi minimum 10.000 permintaan baca per bulan.
• Permintaan API tulis tidak memiliki batas alokasi.

Panggilan ke endpoint API berikut ini tidak disertakan dalam batas alokasi di atas:

• Produk data
• Produk pelaporan
• Produk pajak

Untuk mengurangi volume permintaan API, pertimbangkan penggunaan Stripe Data Pipeline untuk mengekspor data API secara lengkap ke penyedia atau database lokal Anda.