API Terbatas Bukan Berarti Workflow Berhenti: Cara Menangani Rate Limit di n8n

Workflow n8n sering terlihat baik-baik saja saat diuji dengan lima atau sepuluh data. Masalah baru muncul ketika jumlahnya menjadi ratusan: API mulai membalas dengan status 429 Too Many Requests, sebagian data berhenti diproses, atau workflow gagal di tengah jalan.

Ini disebut rate limit, yaitu batas jumlah request yang boleh dikirim ke sebuah layanan dalam periode tertentu. Hampir semua API menerapkan aturan semacam ini untuk menjaga kestabilan sistem. Jadi, ketika workflow menabrak batas tersebut, solusinya bukan sekadar menekan tombol “run” lagi.

Di n8n, penanganan rate limit sebaiknya dianggap sebagai bagian dari desain workflow, bukan tambalan setelah error terjadi.

Kenapa workflow n8n mudah menabrak batas API?

Secara default, sebuah node dapat memproses banyak item dari input. Misalnya, node sebelumnya menghasilkan 500 baris kontak, lalu HTTP Request langsung mengirim satu request untuk setiap item. Dari sisi n8n, alurnya masuk akal. Dari sisi API, 500 request dalam waktu singkat bisa terlihat seperti lonjakan trafik.

Setiap layanan memiliki aturan yang berbeda. Ada API yang membatasi jumlah request per detik, per menit, atau berdasarkan jenis akun. Ada pula yang menerapkan batas berbeda untuk operasi membaca dan menulis. Karena itu, angka aman tidak boleh ditebak hanya dari pengalaman memakai layanan lain.

Fakta: n8n menyediakan pola resmi untuk menangani batas API, termasuk menggunakan node Loop Over Items, node Wait, dan opsi retry pada node yang relevan. Analisis: workflow yang sengaja berjalan sedikit lebih lambat sering kali lebih dapat diandalkan daripada workflow cepat yang harus diulang berkali-kali.

Pola dasar: pecah data, proses bertahap, lalu beri jeda

Untuk kasus sederhana, susun workflow dengan pola berikut:

1. Ambil atau terima data dari sumber awal.
2. Gunakan Loop Over Items untuk memproses data dalam kelompok kecil.
3. Kirim request melalui HTTP Request atau node integrasi yang sesuai.
4. Tambahkan Wait sebelum kelompok berikutnya diproses.
5. Simpan hasil sukses dan catat item yang gagal.

Misalnya, workflow mengambil 1.000 produk dari spreadsheet untuk dikirim ke sistem inventori. Daripada mengirim semuanya sekaligus, Anda dapat memproses 20 item per kelompok, lalu memberi jeda beberapa detik. Angka tersebut bukan aturan universal; gunakan dokumentasi API sebagai dasar dan sesuaikan setelah melihat hasil pengujian.

Node Loop Over Items berguna karena membuat alur pemrosesan lebih terkontrol. Node ini sebelumnya juga dikenal sebagai Split in Batches. Sementara itu, node Wait dapat menunda kelanjutan eksekusi berdasarkan durasi tertentu atau kondisi lain yang tersedia di workflow.

Jangan hanya menambahkan jeda

Jeda tetap bukan obat untuk semua situasi. Jika API membatasi 60 request per menit, jeda dua detik memang memberi sekitar 30 request per menit. Namun, jika workflow berjalan paralel atau ada eksekusi lain yang memakai kredensial dan endpoint sama, batas tetap bisa terlewati.

Perhatikan juga ukuran batch. Batch yang terlalu besar dapat mengurangi manfaat jeda. Batch yang terlalu kecil memang lebih aman, tetapi membuat workflow jauh lebih lama. Tujuannya bukan mencari proses tercepat, melainkan titik yang cukup cepat dan tetap stabil.

Untuk API yang mendukungnya, gunakan operasi batch resmi. Satu request yang berisi 20 item biasanya lebih efisien daripada 20 request terpisah. Namun, pastikan format batch, batas ukuran payload, dan perilaku ketika satu item di dalam batch gagal sudah dipahami.

Gunakan retry dengan hati-hati

Retry berarti mencoba kembali request yang gagal. Fitur ini berguna untuk gangguan sementara, termasuk respons rate limit atau masalah jaringan. Tetapi retry tanpa jeda dapat memperburuk keadaan: request gagal langsung dikirim ulang, lalu gagal lagi, dan seterusnya.

Jika API mengirim header seperti Retry-After, gunakan nilainya sebagai petunjuk kapan request boleh dicoba lagi. Jika informasi itu tidak tersedia, gunakan backoff, yaitu jeda yang semakin panjang pada setiap percobaan. Contohnya:

Percobaan 1: tunggu 2 detik
Percobaan 2: tunggu 5 detik
Percobaan 3: tunggu 15 detik

Di n8n, pengaturan retry dapat dikombinasikan dengan node Wait atau cabang error. Jangan memberikan retry pada semua jenis error. Kesalahan autentikasi, URL yang salah, atau data yang tidak valid biasanya tidak akan selesai hanya dengan mencoba ulang.

Pisahkan error sementara dan error permanen

Workflow yang sehat tidak memperlakukan semua kegagalan dengan cara sama. Error seperti timeout, koneksi terputus, atau status 429 mungkin layak dicoba kembali. Sebaliknya, status 400 karena format data salah perlu diperbaiki atau dikirim ke daftar pengecekan.

Anda dapat membuat cabang berdasarkan kode status respons:

• 2xx: tandai sebagai berhasil dan simpan ID atau respons penting.
• 429: tunggu, lalu coba kembali dengan batas percobaan.
• 5xx: anggap sebagai gangguan sementara, tetapi tetap batasi retry.
• 4xx lainnya: periksa autentikasi, parameter, dan format payload.

Jika menggunakan HTTP Request, aktifkan opsi yang memungkinkan workflow tetap memproses item lain ketika satu request gagal, lalu arahkan hasil error ke jalur pencatatan. Nama opsi dapat berbeda bergantung pada versi n8n dan konfigurasi node, jadi periksa pengaturan node yang digunakan.

Apa artinya bagi kita?

Rate limit bukan sekadar persoalan teknis. Dalam workflow bisnis, kegagalan sebagian data bisa membuat stok tidak sinkron, notifikasi pelanggan tertunda, atau laporan harian tidak lengkap. Karena itu, keberhasilan workflow sebaiknya tidak diukur hanya dari status “Success” di n8n.

Tambahkan ringkasan hasil: berapa item diterima, berapa yang berhasil, berapa yang ditunda, dan berapa yang gagal permanen. Dengan begitu, Anda tidak perlu membuka setiap eksekusi hanya untuk mengetahui apakah semua data sudah masuk.

Yang bisa dilakukan sekarang

1. Periksa dokumentasi API dan cari batas request, ukuran batch, serta header Retry-After.
2. Uji workflow dengan data kecil sebelum menjalankannya untuk seluruh data.
3. Tambahkan Loop Over Items dengan ukuran batch konservatif.
4. Gunakan Wait di antara request atau kelompok data.
5. Batasi jumlah retry dan gunakan jeda yang meningkat.
6. Simpan daftar item gagal agar dapat diproses ulang tanpa mengulang semuanya.
7. Amati durasi eksekusi dan jumlah error selama beberapa hari, lalu sesuaikan parameternya.

Workflow n8n yang baik tidak selalu yang paling cepat. Untuk integrasi API, workflow yang mampu mengatur ritme, menghormati batas layanan, dan menjelaskan apa yang gagal biasanya jauh lebih berguna dalam jangka panjang.

Sumber & bacaan lebih lanjut

• n8n Docs — Handle rate limits
• n8n Docs — Loop Over Items (Split in Batches)
• n8n Docs — Wait node
• n8n Docs — HTTP Request common issues

– Rio Yotto @rioyotto