# Batas tingkat

Pelajari tentang batas tingkat API dan cara mengerjakannya.

Stripe menggunakan pembatasan batas kecepatan untuk memaksimalkan stabilitas API dan mencegah penyalahgunaan, jadi perlakukan batas tersebut sebagai maksimum dan hindari beban yang tidak perlu.

Jika Anda melampaui batas, Anda akan mendapatkan respons status HTTP `429 Too Many Requests`. Untuk saran tentang menangani kesalahan `429`, lihat [Menangani pembatasan dengan baik](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully).

## Batas kecepatan

Secara umum, batas kecepatan diukur dalam permintaan API per detik, per akun Stripe. Batas kecepatan global berlaku untuk total penggunaan API per akun, sementara beberapa endpoint memiliki batas tambahannya sendiri.

Stripe menganggap setiap operasi API bernama sebagai endpoint terpisah (misalnya, `POST /v1/payment_intents` dan `GET /v1/payment_intents/{id}` adalah endpoint terpisah). Permintaan ke `GET /v1/payment_intents/{id}` untuk ID PaymentIntent yang berbeda dihitung ke dalam batas endpoint yang sama.

| Sumber daya | Batas |
| --- | --- |
| **Batas kecepatan API global** | - *Mode live* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments): 100 permintaan per detik
- *Sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes): 25 permintaan per detik |
| Endpoint API individual (kecuali jika disebutkan lain) | 25 permintaan per detik |
| [Payment Intents API](https://docs.stripe.com/api/payment_intents.md) | 1000 permintaan pembaruan per objek PaymentIntent, per jam |
| [Subscriptions API](https://docs.stripe.com/api/subscriptions.md) | - 10 invoice baru per langganan, per menit
- 20 invoice baru per langganan, per hari
- 200 pembaruan kuantitas per langganan, per jam |
| [Files API](https://docs.stripe.com/api/files.md) | - 20 permintaan baca per detik
- 20 permintaan tulis per detik |
| [Payouts API](https://docs.stripe.com/api/payouts.md) | - 15 permintaan [create](https://docs.stripe.com/api/payouts/create.md) per detik
- 30 [permintaan konkuren](https://docs.stripe.com/rate-limits.md#concurrency-limits) per bisnis |
| Akun *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients), termasuk keduanya:
- [Accounts v2](https://docs.stripe.com/api/v2/core/accounts.md)
- [Accounts v1](https://docs.stripe.com/api/accounts.md) | - *Mode live* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments): Buat 30 akun per detik
- *Sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes): Buat 5 akun per detik |
| [Search API](https://docs.stripe.com/search.md#rate-limits)1 | 20 permintaan baca per detik |
| [Issuing](https://docs.stripe.com/issuing.md) | Batas pembuatan kartu bergantung pada negara dan industri akun penerbit. |

Pertimbangkan [Sigma](https://docs.stripe.com/data/sigma.md) atau [Data Pipeline](https://docs.stripe.com/data/data-pipeline.md) untuk opsi yang lebih efisien bagi tugas analitik intensif data.

## Batas konkurensi

Batas konkurensi membatasi jumlah permintaan aktif secara simultan, terpisah dari batas kecepatan. Tidak seperti batas kecepatan, yang secara umum diatur ulang setelah satu detik, batas konkurensi menghitung berapa banyak permintaan yang sedang berlangsung pada saat tertentu. Mencapai batas konkurensi lebih jarang terjadi daripada kesalahan batas kecepatan, dan biasanya mengindikasikan permintaan API yang berumur panjang atau intensif sumber daya seperti permintaan daftar atau yang menyertakan [ekspansi](https://docs.stripe.com/expand.md).

## Respons dengan batas kecepatan

Permintaan yang dibatasi kecepatannya mengembalikan kode status HTTP `429 Too Many Requests`, dan menyertakan header `Stripe-Rate-Limited-Reason` yang menjelaskan alasan permintaan tersebut dibatasi kecepatannya. Kemungkinan nilai untuk header ini adalah:

| Nilai header | Deskripsi |
| --- | --- |
| `global-rate` | Anda melampaui batas kecepatan global. Anda dapat mencegahnya dengan mengirimkan permintaan pada kecepatan yang lebih rendah. |
| `endpoint-rate` | Anda melampaui batas kecepatan untuk permintaan ke endpoint API spesifik ini. Anda dapat mencegahnya dengan mengirimkan permintaan ke endpoint ini pada kecepatan yang lebih rendah. |
| `global-concurrency` | Anda melampaui batas konkurensi global. Anda dapat mencegahnya dengan mengirimkan lebih sedikit permintaan secara bersamaan. |
| `endpoint-concurrency` | Anda melampaui batas konkurensi untuk permintaan ke endpoint API spesifik ini. Anda dapat mencegahnya dengan mengirimkan lebih sedikit permintaan secara bersamaan ke endpoint spesifik ini. |
| `resource-specific` | Anda melampaui batas kecepatan terkait permintaan ke semua endpoint dalam sumber daya ini, misalnya endpoint pembaruan dan pembuatan dari langganan. Anda dapat mencegahnya dengan mengirimkan permintaan ke endpoint di seluruh sumber daya tersebut pada kecepatan yang lebih rendah. |

Jika permintaan mengembalikan kode status `429` tanpa header ini, hal tersebut bukan hasil dari batas kecepatan. Itu mungkin merupakan [batas waktu penguncian](https://docs.stripe.com/rate-limits.md#object-lock-timeouts).

## 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](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully)).

- 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](https://support.stripe.com/).

- Mengeluarkan banyak permintaan yang berumur panjang dapat memicu pembatasan konkurensi. Permintaan bervariasi dalam jumlah sumber daya server Stripe yang digunakannya, dan permintaan yang lebih intensif sumber daya dapat memakan waktu lebih lama serta berisiko menyebabkan pembatas konkurensi membuang permintaan baru. Persyaratan sumber daya sangat bervariasi, tetapi permintaan daftar dan permintaan yang menyertakan [ekspansi](https://docs.stripe.com/expand.md) umumnya menggunakan lebih banyak sumber daya dan memakan waktu lebih lama untuk dijalankan. Kami menyarankan untuk membuat profil durasi permintaan API Stripe dan mengawasi waktu tunggu habis untuk mengidentifikasi permintaan yang lambat di luar dugaan.

## 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](https://en.wikipedia.org/wiki/Thundering_herd_problem).

Pendekatan yang lebih canggih adalah mengontrol lalu lintas ke Stripe di tingkat global, dan membatasinya jika Anda mendeteksi pembatasan batas kecepatan yang substansial. Teknik umum untuk mengontrol penggunaan API adalah dengan menerapkan [algoritme pembatasan batas kecepatan token bucket](https://en.wikipedia.org/wiki/Token_bucket) sisi client. Implementasi token bucket atau pustaka tersedia untuk sebagian besar 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 yang lain atau proses Stripe tengah mengaksesnya. Jika Anda melihat kesalahan ini hanya sesekali, coba kembali permintaan. Jika Anda sering melihat kesalahan ini dan tengah membuat beberapa permintaan bersamaan ke satu objek, buat permintaan secara berseri atau dengan tingkat 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](https://docs.stripe.com/api/request_ids.md).

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](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully)). Namun, tak seperti kesalahan pembatasan laju, mekanisme coba ulang otomatis yang dibangun ke [SDK](https://docs.stripe.com/sdks.md) Stripe mencoba ulang `429` yang disebabkan oleh batas waktu penguncian:

#### Ruby

```ruby
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](https://docs.stripe.com/data.md)
- [Produk pelaporan](https://docs.stripe.com/stripe-reports.md)
- [Produk pajak](https://docs.stripe.com/tax.md)

Untuk mengurangi volume permintaan API Anda, pertimbangkan untuk menggunakan [Data Pipeline](https://docs.stripe.com/data/data-pipeline.md) untuk ekspor lengkap data API ke basis data lokal atau penyedia Anda.

> #### Saring permintaan untuk membatasi panggilan yang di-paginasi
> 
> Beberapa endpoint daftar mengembalikan hasil [beberapa halaman](https://docs.stripe.com/api/pagination.md) dan mungkin memerlukan beberapa permintaan untuk mengembalikan rangkaian lengkap objek API bagi operasi daftar. Terapkan filter bila memungkinkan guna mempersempit hasil daftar Anda.

## Request a limit increase

Request a limit increase for high-traffic applications through [Stripe Support](https://support.stripe.com/contact). If you request a large increase, contact Stripe Support at least 6 weeks in advance.