API Hız Sınırlarını Yönetme: Wait, Batching, Retry, Pagination

Üçüncü taraf API'lere karşı kendi workflow'larını kuran herkes er ya da geç 429 yanıtıyla karşılaşır: "Too Many Requests". Özellikle toplu işlemede, örneğin yüzlerce CRM kişisini zenginleştirirken veya büyük ürün kataloglarını senkronize ederken bu bir istisna değil, kuraldır. n8n bunun için birbiriyle birleştirilebilen birkaç yerleşik araç sunar: Wait düğümü, HTTP Request düğümündeki Retry on Fail ayarı, Batching ve pagination kontrolü. Güncelleme: Temmuz 2026.

Numara, rate limit'leri "çözen" tek bir özellik bulmak değil, ilgili kullanım durumu için doğru kombinasyonu seçmektir. Ara sıra başarısız olan tek bir API çağrısı, on bin kayıt üzerinde bir döngüden farklı bir şey gerektirir. Aşağıda resmi n8n dokümantasyonuna dayanarak her iki senaryoyu da ele alıyoruz.

Bir rate limit sorunu nasıl anlaşılır

Rate limit'ler hakkındaki n8n dokümantasyonuna göre bir servis genellikle çok fazla isteği HTTP 429 durum koduyla ve servisin "sizden çok fazla istek" aldığını belirten bir hata mesajıyla bildirir. Bu mesaj, bir istek başarısız olduğunda düğüm çıktısında görünür ve kimlik bilgilerinin veya URL'nin yanlış olmadığının, sadece kısa sürede çok fazla isteğin gönderildiğinin ilk işaretidir. Sorun giderme için önemli: bir 429 hatası, daha önce yüzlerce kez hatasız çalışmış bir workflow'un ortasında da ortaya çıkabilir, örneğin bir kampanya veya trafik zirvesi sırasında üçüncü taraf sağlayıcı limitini geçici olarak sıkılaştırdığı için. Aynı API ile sık çalışanların, workflow üretime geçmeden önce ilgili rate limit dokümantasyonunu bilmesi gerekir.

Retry on Fail: Tek tek istekleri otomatik olarak tekrarlama

Ara sıra ve sistematik olmayan 429 hatalarına sahip workflow'lar için genellikle HTTP Request düğümündeki yerleşik tekrar deneme mantığı yeterlidir. Düğümün Settings kısmında Retry On Fail seçeneğini etkinleştirir ve iki değer ayarlarsın:

• Max Tries n8n'in bir başarısızlıktan sonra isteği en fazla kaç kez tekrar deneyeceğini belirler.
• Wait Between Tries (ms) denemeler arasındaki bekleme süresini milisaniye cinsinden belirler.

HTTP Request düğümünün yaygın sorunlarıyla ilgili dokümantasyona göre bu ayarı özellikle rate limit'lere karşı kullanıyorsan, Wait Between Tries (ms) değerini servisin limitinin üzerinde bir değere ayarlamalısın. Örneğin bir API saniyede bir isteğe izin veriyorsa, ikinci denemenin aynı limite tekrar takılmaması için 1000 milisaniye ayarla. Bu yöntemin avantajı: aynı düğümde birkaç tıklamayla halledilir, canvas'ta ekstra düğüm gerekmez. Dezavantajı: bir döngüde çok fazla item olduğunda bekleme süresi hızla katlanır ve ek bir kontrol olmadan n8n, ilk hata geri dönmeden önce bile mümkün olduğunca çok istek göndermeye devam eder.

HTTP Request düğümünde Batching: istekleri bilinçli olarak yavaşlatma

Bir API'nin sıkı limitleri olduğunu baştan biliyorsan, sadece hatalara tepki vermek yerine istek oranını önceden kontrol etmek daha mantıklıdır. Bunun için HTTP Request düğümü, Add Option > Batching altında iki ayar sunar:

• Items per Batch: her istek turunda kaç girdi item'ının işleneceği.
• Batch Interval (ms): batch'ler arasındaki bekleme süresi, milisaniye cinsinden.

Dokümantasyona göre bu batching seçeneği, işlevsel olarak Loop Over Items ile Wait düğümünün kombinasyonuna karşılık gelir, sadece tek bir düğüme entegre edilmiş halidir. Örneğin bir servise saniyede bir istek göndermek istiyorsan, Batch Interval (ms) değerini 1000 olarak ayarla. Saniye başına değil dakika başına limiti olan API'ler için buna göre hesaplarsın, örneğin dakikada 60 istek, tek tek istekler arasında 1000 milisaniyelik bir aralığa veya batch başına birden fazla item olduğunda daha büyük bir aralığa karşılık gelir. Toplu işleme için bu, sorunu kökten ele aldığı için başarısızlıktan sonra tepki vermekten daha sağlam bir temel ayardır.

Loop Over Items ve Wait düğümü: ritim üzerinde tam kontrol

Batch'ler arasında kendi mantığına ihtiyaç duyduğun durumlar için, örneğin loglama, koşullu bir dallanma veya yanıta göre bekleme süresini dinamik olarak ayarlama gibi, Loop Over Items ile kendi Wait düğümünü birleştirirsin. Kurulum: Loop Over Items düğümünü API çağrısından önce yerleştir, ardından Wait düğümünü ekle ve çıkışını tekrar Loop Over Items düğümüne bağla. Böylece her batch'ten veya her tek item'dan sonra, bir sonraki tur başlamadan önce bilinçli olarak duraklayan bir döngü oluşur.

Wait düğümünün kendisi, Wait düğümü hakkındaki n8n dokümantasyonuna göre çalışan bir yürütmeyi durdurmak ve daha sonra aynı verilerle kaldığı yerden devam ettirmek için tasarlanmıştır. Rate limit konusu için özellikle After Time Interval modu önemlidir: saniye, dakika, saat veya gün cinsinden bir süre belirtirsin ve workflow tam olarak bu kadar süre duraklar. Bilinmesi gereken önemli bir nokta: 65 saniyenin altındaki bekleme sürelerinde n8n, yürütme verilerini veritabanına aktarmaz, bu nedenle bekleme belleğinde hafif bir şekilde çalışır. Daha uzun bekleme sürelerinde n8n önbelleğe almayı otomatik olarak devralır, bu da workflow'u örnek yeniden başlatmalarında bile güvenilir şekilde devam ettirilebilir kılar. After Time Interval dışında düğüm ayrıca At Specified Time, On Webhook Call ve On Form Submitted modlarını da destekler; bunlar dış onaylar veya planlanmış yürütmeler gibi başka senaryolar için düşünülmüştür, ancak saf rate limiting için nadiren gereklidir.

Her şeyi bir kerede yüklemek yerine pagination'ı düzgün yönetme

Rate limit hatalarının yaygın bir nedeni aslında isteklerin sıklığı değil, miktarıdır: on bin kaydı tek, frenlenmemiş bir geçişte sayfalamaya çalışan biri, kısa sürede arka arkaya çok fazla istek üretir. Pagination hakkındaki n8n dokümantasyonuna göre HTTP Request düğümü bunun için farklı modları destekler:

• Response Contains Next URL: API, yanıtında bir sonraki sayfanın URL'sini doğrudan döndürür, bunu bir ifade aracılığıyla okursun, örneğin `{{ $response.body["next-page"] }}`.
• Update a Parameter in Each Request: istekler arasında bir query veya body parametresini kendin artırırsın, örneğin sıfırdan başlayan bir sayım için `{{ $pageCount + 1 }}` ile; bu, birden başlayan bir API pagination'ına uydurulmalıdır.

Dokümantasyon, her API'nin pagination'ı farklı şekilde uyguladığını açıkça belirtir. Bu nedenle önceden servisin next-URL'ler, sayfa numaraları veya offset parametreleriyle mi çalıştığını ve sayfa başına en fazla kaç sonuca izin verildiğini kontrol etmelisin. Sayfa boyutunu genellikle düğüm ayarlarında `limit` gibi kendi query parametren üzerinden belirlersin. Pagination'ı batching veya sayfa çağrıları arasında bir Wait düğümüyle birleştirirsen, kapsamlı bir veri dışa aktarımının, asıl işleme başlamadan önce sadece hızı yüzünden limite takılmasını önlersin.

Pratik desenler: hangi durum için hangi kombinasyon

Pratikte hangi aracın ne zaman devreye girdiğine dair kabaca bir sınıflandırma yapmakta fayda var:

• Düşük hacimde ara sıra görülen 429 hataları: genellikle uygun bir Wait Between Tries ile Retry On Fail yeterlidir.
• Yüksek hacimde bilinen, sabit bir rate limit: servisin limitine uygun bir aralıkla HTTP Request düğümünde Batching.
• Çağrılar arasında daha karmaşık mantık, örneğin yanıt başlığına göre dinamik bekleme süreleri veya ek dallanmalar: kendi Wait düğümüyle birleştirilmiş Loop Over Items.
• Birden fazla sayfada büyük veri miktarları: API'ye uygun bir pagination modu seçmek ve ek olarak Batching veya Wait ile yumuşatmak.

Pratikte tam bir workflow için tek bir aracın yeterli olması nadirdir. Tipik bir desen, veri almak için pagination, işleme sırasında ölçülü bir batch aralığı ve ayrıca yavaşlatılmış oranın bile ara sıra bir 429'a yol açtığı anlar için bir güvenlik ağı olarak Retry On Fail'dir. Böylece üçüncü taraf sağlayıcının hiçbir zaman yük altına girmeyeceği şansına güvenmek yerine, workflow'unun hızı ve güvenilirliği üzerinde kontrolü elinde tutarsın.

Sık sorulan sorular

Retry On Fail ile Batching arasındaki fark nedir?

Retry On Fail, ancak bir istek zaten başarısız olduktan sonra tepki verir ve belirlenen bir bekleme süresinden sonra tekrar dener. Batching daha önceden devreye girer ve baştan itibaren kaç isteğin ne aralıkla gönderileceğini sınırlar. Bilinen, sabit limitler için Batching daha temiz bir çözümdür; ara sıra öngörülemeyen başarısızlıklar için Retry On Fail bunu bir güvence olarak tamamlar.

Wait düğümü yürütmeyi hangi bekleme süresinden itibaren veritabanına kaydeder?

n8n dokümantasyonuna göre Wait düğümü, yürütme verilerini yalnızca 65 saniye ve üzeri bekleme sürelerinde veritabanına aktarır. Daha kısa duraklamalar bu ek adım olmadan hafif şekilde çalışır, bu da saniyenin küçük kesirlerinden birkaç saniyeye kadar duraklamalar içeren çoğu rate limit senaryosu için yeterlidir.

Aynı workflow içinde Batch Interval ile bir Wait düğümünü aynı anda kullanabilir miyim?

Evet, bu hatta yaygın bir desendir. HTTP Request düğümündeki Batching, asıl işleme sırasındaki sürekli yavaşlatmayı kapsar; ek bir Wait düğümü ise workflow'un başka bir yerinde, örneğin pagination sırasında tek tek sayfa çağrıları arasında veya özellikle sınırlı bir sonraki adımdan önce, hedeflenmiş ve daha uzun bir duraklama ekleyebilir.

Bir API'nin tam rate limitini bilmiyorsam ne yapmalıyım?

İstekler arasında örneğin 1000 ile 2000 milisaniye gibi daha büyük bir aralıkla temkinli başla ve 429 hatalarının devam edip etmediğini gözlemle. Birçok API, limiti yanıt başlıklarında da belirtir; bunu HTTP Request düğümünde değerlendirip bekleme süresini dinamik olarak ayarlamak için kullanabilirsin. Ayrıca ilk tahminin çok dar olması ihtimaline karşı etkinleştirilmiş bir Retry On Fail güvenlik ağı olarak yardımcı olur.

Büyük veri miktarlarında rate limit'leri önlemek için tek başına Retry On Fail yeterli mi?

Güvenilir şekilde değil. Retry On Fail, başarısız olan tek tek istekleri tekrarlar ama n8n'in batching olmadan büyük bir döngüde arka arkaya çok fazla istek göndermesini engellemez. Yüksek hacimde, Wait düğümüyle birleştirilmiş Batching veya Loop Over Items kombinasyonu daha sağlam bir seçimdir; Retry On Fail ek bir güvence olarak yararlı olmaya devam eder.