Rate limit

Rate limit mendefinisikan jumlah maksimum permintaan yang dapat dibuat oleh suatu aplikasi ke API dalam periode waktu tertentu. Mekanisme ini sangat penting untuk menjaga kesehatan dan keandalan layanan secara keseluruhan.

Mengapa kami menggunakan rate limiting

Stabilitas dan performa API

• Mencegah satu klien membanjiri server dengan permintaan yang berlebihan.
• Memastikan waktu respons yang konsisten dan dapat diprediksi untuk semua klien.
• Melindungi layanan back-end dari lonjakan traffic yang tidak terduga.
• Mempertahankan pola beban yang stabil dan terkontrol pada infrastruktur.

Keamanan

• Memperkuat pertahanan terhadap upaya serangan, seperti brute force.
• Mengurangi risiko distributed denial-of-service (DDoS).
• Mengurangi dampak yang disebabkan oleh integrasi yang diimplementasikan dengan buruk.
• Membatasi potensi kerusakan akibat kredensial API yang dikompromikan.

Alokasi sumber daya

• Memastikan akses yang seimbang ke sumber daya API untuk semua klien.
• Mencegah penggunaan berlebihan oleh sebagian pihak yang menurunkan pengalaman pengguna lain.
• Memungkinkan prioritas traffic sesuai kriteria dan kebutuhan bisnis.
• Mendorong praktik konsumsi API yang lebih efisien dan berkelanjutan.

Cara kerja rate limiting

Setiap panggilan API dihitung terhadap batas permintaan-per-detik yang diizinkan. Nilai default adalah 10 RPS per tenant. Ketika batas terlampaui, API mengembalikan HTTP 429 Too Many Requests.

Konfirmasi dengan tim Onboarding Anda

Batas yang tepat dikonfigurasi per tenant. Hubungi tim Onboarding Anda untuk mengonfirmasi batas yang diterapkan pada akun Anda sebelum melakukan sizing untuk integrasi throughput tinggi.

Menangani error 429

Minta peningkatan rate limit

Jika operasi Anda akan mengalami peningkatan volume permintaan (sementara atau permanen), beri tahu tim Unico untuk menaikkan rate limit untuk environment Anda. Permintaan ini harus dibuat sebelum volume sebenarnya meningkat untuk menghindari aplikasi Anda menjadi tidak beroperasi.

Tinjau perilaku aplikasi

• Audit kode Anda untuk mengidentifikasi pola penggunaan API yang tidak efisien.
• Periksa loop yang tidak disengaja atau panggilan API yang redundan.
• Distribusikan permintaan secara lebih merata dari waktu ke waktu alih-alih mengirimnya dalam burst besar.

Implementasikan caching

• Cache data yang sering diakses yang jarang berubah.
• Gunakan OAuth2 access token selama TTL penuh 1 jam — jangan panggil POST /oauth2/token per permintaan.
• Implementasikan strategi invalidasi cache yang sesuai.

Gunakan webhook daripada polling

Berlangganan ke Webhooks and Events untuk PROCESS_STATE_FINISHED daripada melakukan polling GET /client/v1/process/\{id\}. Loop polling dapat dengan mudah menghabiskan anggaran GET-process pada traffic berat.

Apa yang terjadi ketika Anda mencapai batas

Platform mengembalikan:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

Header	Arti
Retry-After	Jumlah detik yang harus ditunggu sebelum mencoba ulang. Patuhi ini.

Jika Retry-After tidak ada, gunakan exponential backoff (1d, 2d, 4d, 8d, …) dengan batas maksimum 60d.

Pertimbangan konkurensi

Rate limit membatasi permintaan per menit, tetapi platform juga memiliki batas konkurensi di tingkat infrastruktur. Bahkan jika Anda memiliki anggaran untuk 100 permintaan/menit, mengirim semua 100 di detik yang sama lebih mungkin ditolak daripada menyebarkannya sepanjang menit.

Untuk integrasi throughput tinggi, targetkan RPS yang stabil daripada burst.

Pengiriman webhook Magic Link

Trully memiliki kuota pengiriman sendiri untuk Webhook V2. Server webhook diharapkan merespons dalam 1 menit; respons yang lebih lambat akan dibuang (proses pengguna tidak terpengaruh). Untuk pemrosesan yang konsisten, konfirmasi webhook dengan cepat dan proses secara asinkron.

Langkah berikutnya

• Authentication — strategi caching token.
• Webhooks and Events — mengganti polling dengan push.
• Error codes > Retry policy — kapan (dan kapan tidak) harus mencoba ulang.