Batas tingkat

Kami menggunakan proteksi terhadap lonjakan lalu lintas masuk untuk memaksimalkan stabilitas API. Jika Anda mengirim banyak permintaan sekaligus, Anda mungkin akan menerima respons kesalahan 429.

Pembatas API

Kami memberlakukan beberapa pembatas API, termasuk pembatas tarif dan konkurensi. Anggap batasan sebagai batas maksimum dan hindari beban yang tidak perlu. Untuk mencegah penyalahgunaan, kami dapat mengurangi batas Anda. Untuk saran tentang penanganan kesalahan 429, lihat Menangani pembatasan secara efisien. Jika Anda melihat peningkatan permintaan dengan batas kecepatan, hubungi Dukungan Stripe.

Minta kenaikan batas untuk aplikasi dengan lalu lintas tinggi melalui Dukungan Stripe. Jika Anda meminta kenaikan signifikan, hubungi Dukungan Stripe minimal 6 minggu sebelumnya.

Pembatas kecepatan

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.

• Payment Intents API: 1.000 operasi pembaruan per PaymentIntent, per jam.
• Files API: 20 operasi baca dan 20 operasi tulis per detik.
• Search API: 20 operasi baca per detik.
• API Langganan:
  • 10 invoice baru per langganan, per menit.
  • 20 invoice baru per langganan, per hari.
  • 200 pembaruan kuantitas per langganan, per jam.
• Create Payout API: 15 permintaan per detik dan 30 permintaan serentak per merchant.
• Connect: Platform dapat membuat hingga 5 akun per detik di sandbox dan 30 akun per detik dalam mode live.
• Issuing: Pembuatan kartu memiliki batas kecepatan yang bergantung pada negara dan industri bisnis.

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).

• Mengeluarkan banyak permintaan berumur panjang dapat memicu pembatasan. Permintaan bervariasi dalam jumlah sumber daya server Stripe yang mereka gunakan, dan permintaan yang lebih intensif sumber daya dapat memakan waktu lebih lama dan berisiko menyebabkan pembatas konkurensi melepaskan permintaan baru. Persyaratan sumber daya sangat bervariasi, tetapi daftar permintaan dan permintaan yang menyertakan ekspansi umumnya menggunakan lebih banyak sumber daya dan membutuhkan waktu lebih lama untuk dijalankan. Sebaiknya buat profil durasi permintaan Stripe API dan perhatikan batas waktu untuk mencoba dan menemukan permintaan yang lambat secara tak terduga.

• Peningkatan tiba-tiba dalam volume charge seperti penjualan kilat mungkin mengakibatkan pembatasan kecepatan. Kami mencoba mengatur kecepatan kami cukup tinggi sehingga lalu lintas pembayaran yang akan datang tidak pernah melebihi batas, tetapi jika Anda memperkirakan adanya lonjakan yang mengharuskan Anda meningkatkan batas lebih dari yang tercantum di atas, hubungi Dukungan Stripe.

Mengatasi pembatasan

Pantau kode status 429 dan terapkan mekanisme percobaan ulang untuk menangani pembatasan jumlah permintaan. Ikuti jadwal mundur eksponensial untuk mengurangi volume permintaan saat diperlukan, dan tambahkan elemen acak pada jadwal tersebut guna menghindari efek serbuan serentak.

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.

API Stripe mengunci objek pada beberapa operasi agar beban kerja bersamaan tidak saling mengganggu dan menghasilkan hasil yang tidak konsisten. Kesalahan di atas disebabkan oleh permintaan yang mencoba memperoleh kunci yang sudah dipegang di tempat lain, dan mengalami batas waktu setelah tidak dapat diperoleh tepat waktu. Stripe tidak memproses permintaan yang gagal ini, yang berarti permintaan tersebut tidak diberi ID permintaan.

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 akun Anda tidak boleh melebihi rata-rata 500 per transaksi. Misalnya, jika Anda memproses 100 transaksi dalam waktu 30 hari, Anda tidak boleh melebihi 50.000 permintaan API baca selama periode tersebut.

• 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 dihitung selama periode bergulir 30 hari (30 hari terakhir).

• 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.