Shopify API Rate Limit ve Stok Senkronizasyon Hataları Nasıl Çözülür?

Shopify API Rate Limit Nedir? Shopify API rate limit, bir uygulamanın belirli bir zaman aralığında Shopify Admin API’ye gönderebileceği istek sayısını veya sorgu maliyetini sınırlayan, mağaza performansını korumaya yönelik teknik kısıtlama mekanizmasıdır.

Shopify, REST Admin API için “leaky bucket” (sızdıran kova) modelini, GraphQL Admin API için ise sorgu karmaşıklığına dayalı “cost-based” (maliyet tabanlı) modeli kullanır (Shopify.dev, 2025). İki model de aynı amaca hizmet eder mağaza altyapısının tek bir uygulamanın aşırı yüküyle yavaşlamasını önlemek ama farklı matematikle çalışır ve farklı hata mesajları üretir.

Çoklu pazaryeri veya ERP entegrasyonu çalıştıran mağazalarda rate limit sorunu, genelde stok senkronizasyon hatası olarak kendini gösterir: ürün stoğu bir kanalda güncellenirken diğer kanala geç yansır veya hiç yansımaz. Bu rehber, rate limit mekanizmasının matematiğini, stok senkronizasyonunda neden özellikle bu limite çarpıldığını ve bulk operations API’nin bu sorunu nasıl çözdüğünü teknik derinlikte ele alır bu, rakip kaynaklarda genelde yüzeysel geçilen bir konudur.

Shopify REST API Leaky Bucket Modeli Nasıl Çalışır?

Leaky bucket modeli, her mağazaya sabit kapasiteli bir “kova” (bucket) tahsis eder; bu kova standart mağazalarda 40 istek kapasitesine sahiptir ve saniyede 2 istek hızında boşalır (Shopify.dev, 2025). Her API çağrısı kovaya bir birim ekler, kova taştığında (40’ı aştığında) yeni istekler 429 durum koduyla reddedilir.

Bu modelin pratik sonucu şudur: kısa bir anda 40’tan fazla istek gönderilirse ilk 40 istek kabul edilir, sonrakiler reddedilir; ancak istekler saniyede 2’yi aşmayacak şekilde yayılırsa kova hiç dolmaz ve hiçbir istek reddedilmez. Kovanın dolu kapasitesi, Shopify Plus mağazalarında standart mağazalara göre daha yüksektir.

Quotable: Leaky bucket modelinde sorun istek sayısı değil, isteklerin zaman içindeki yoğunluğudur; aynı 100 istek, 5 saniyeye yayılırsa sorunsuz geçer ama 1 saniyede gönderilirse büyük kısmı reddedilir.

Her API yanıtı, X-Shopify-Shop-Api-Call-Limit header’ında mevcut kova doluluğunu 32/40 gibi bir formatta bildirir. Bir entegrasyonun bu header’ı her yanıtta okuyup kalan kapasiteye göre isteklerini yavaşlatması, 429 hatasına düşmeden önce önleyici bir kontrol sağlar.

GraphQL Cost-Based Rate Limit Nasıl Hesaplanır?

GraphQL Admin API’de her sorgu, döndürdüğü alan sayısına ve iç içe geçme (nesting) derinliğine göre bir maliyet puanı alır; basit bir sorgu birkaç puan tüketirken, çok sayıda ilişkili veri çeken derin bir sorgu yüzlerce puana ulaşabilir. Standart mağazalarda bu puan havuzu dakikada 1000 puan olarak yenilenir (Shopify.dev, 2025).

Bu model, REST’ten farklı olarak “kaç istek gönderildiğini” değil “ne kadar veri talep edildiğini” ölçer. Tek bir GraphQL isteğiyle 50 ürünün tüm varyantlarını, resimlerini ve stok bilgisini birlikte çekmek, aynı veriyi REST ile 50 ayrı istekte çekmekten daha az rate limit tüketebilir çünkü GraphQL gereksiz alanları hariç tutma imkanı sunar.

İpucu: Bir GraphQL sorgusunun maliyetini göndermeden önce tahmin etmek için Shopify, sorgunun extensions.cost.requestedQueryCost alanında maliyeti önceden hesaplayıp yanıtla birlikte döner. Yüksek maliyetli sorguları küçük parçalara bölmek, tek seferde limit aşımını önler.

Peki bu maliyet mantığı pratikte ne anlama geliyor? Bir entegrasyon, 1000 ürünün stok bilgisini tek bir derin sorguyla çekmeye çalışırsa dakikalık 1000 puanlık havuzu tek seferde tüketebilir; bunun yerine sorguyu sayfalama (pagination) ile 50’şer ürünlük parçalara bölmek, havuzu zaman içine yayarak aynı işi limite takılmadan tamamlar.

Çoklu Pazaryeri ve ERP Entegrasyonunda Stok Senkronizasyonu Neden Rate Limit’e Çarpar?

Stok senkronizasyon hataları, genelde birden fazla sistemin (pazaryeri, ERP, Shopify) aynı anda ve bağımsız olarak stok güncellemesi göndermesinden kaynaklanır; her sistem kendi zamanlamasıyla API’ye istek attığında toplam istek hacmi tek bir mağazanın rate limit kovasını hızla doldurur. Bu senaryoda hata genelde “bazı ürünlerin stoğu güncellenmedi” şikayeti olarak fark edilir.

Bir mağaza aynı anda Trendyol, Hepsiburada ve bir muhasebe yazılımıyla senkronize çalışıyorsa, her üç sistemin de kendi zamanlayıcısıyla (örneğin her 5 dakikada bir) Shopify’a stok güncelleme isteği göndermesi, bu isteklerin aynı dakikada çakışmasına neden olabilir. Çakışma anında kovanın 40 istek kapasitesi aşılır ve geç gelen istekler 429 hatasıyla reddedilir.

Uzak Durulması Gereken Risk: 429 hatası alan bir istek loglanmadan sessizce göz ardı edilirse, o ürünün stok bilgisi güncellenmeden kalır ve mağaza fiilen stokta olmayan bir ürünü satmaya devam edebilir. Her 429 yanıtı mutlaka yeniden deneme kuyruğuna alınmalıdır.

Bu tür çoklu kanal senkronizasyon sorunlarının kök nedeni çoğunlukla mimari tasarımdır, rate limit sadece belirtiyi ortaya çıkarır. Pazaryeri tarafındaki entegrasyon mimarisi ve senkronizasyon sıklığı ayarları Shopify pazaryeri entegrasyonu rehberi içinde, ERP tarafındaki veri eşleştirme mantığı ise Shopify ERP ve muhasebe entegrasyonu rehberinde ayrıca ele alınır.

Retry-After Header ile Rate Limit Yönetimi Nasıl Yapılır?

Shopify, bir istek rate limit nedeniyle reddedildiğinde 429 durum kodu ile birlikte Retry-After header’ını döner; bu header, saniye cinsinden ne kadar beklenmesi gerektiğini belirtir ve entegrasyonun bu süreyi beklemeden yeniden deneme yapmaması gerekir. Bu header’ı yok sayıp anında tekrar istek göndermek, kovayı daha da doldurup ardışık 429 hatalarına yol açar.

Doğru bir retry stratejisi, Retry-After değerini okuyup tam o süre kadar bekledikten sonra isteği tekrar göndermeli ve ardışık başarısızlıklarda bekleme süresini kademeli olarak artırmalıdır (exponential backoff). Bu yaklaşım, mağazanın kovasının tekrar boşalmasına zaman tanır.

Quotable: Retry-After header’ını yok sayan bir entegrasyon, rate limit sorununu çözmek yerine derinleştirir her erken yeniden deneme, kovayı bir kez daha doldurma riski taşır.

1. API yanıtında 429 durum kodu geldiğinde isteği hemen tekrar göndermeyin.
2. Retry-After header’ındaki saniye değerini okuyun.
3. Belirtilen süre kadar bekleyin, ardından isteği yeniden gönderin.
4. Art arda 429 alınıyorsa bekleme süresini bir önceki denemenin iki katına çıkarın.
5. Belirli bir deneme sayısından sonra (örneğin 5 deneme) isteği kuyruğa alıp manuel inceleme için işaretleyin.

Kritik Not: Retry mantığı sonsuz döngüye girecek şekilde kurulmamalı. Belirli bir deneme sınırından sonra istek başarısız sayılıp ayrı bir hata kuyruğuna yazılmalı; aksi halde tek bir sorunlu istek, sistemin geri kalanını da rate limit’e sürükleyebilir.

Bulk Operations API Stok Senkronizasyonunu Nasıl Çözer?

Bulk Operations API, binlerce kaydı tek tek istek göndermek yerine tek bir asenkron iş (job) olarak Shopify’a gönderip sonucun bir dosya halinde geri alınmasını sağlayan mekanizmadır; bu yöntem rate limit hesaplamasının dışında, ayrı bir kuyrukta işlenir (Shopify.dev, 2025). Yüksek hacimli stok güncellemelerinde bu, rate limit sorununu kökünden çözen tek resmi yöntemdir.

Bulk operations, hem veri okuma (bulk query) hem de veri yazma (bulk mutation) için kullanılabilir. Binlerce ürünün stok miktarını tek seferde güncellemek gereken bir senkronizasyon işleminde, her ürün için ayrı bir GraphQL mutasyonu göndermek yerine tüm güncellemeler tek bir JSONL dosyası olarak paketlenip bulk mutation ile gönderilir.

İpucu: 500’den fazla kaydı aynı anda güncelleyen her senkronizasyon işlemi, standart API çağrıları yerine Bulk Operations API ile yeniden tasarlanmalı. Bu değişiklik, rate limit hatalarını pratikte sıfıra indirir çünkü iş Shopify’ın kendi arka plan kuyruğunda işlenir.

Bulk operations’ın tek dezavantajı, sonucun anlık değil asenkron dönmesidir iş tamamlandığında bir webhook (bulk_operations/finish) tetiklenir ve sonuç dosyası bir URL üzerinden indirilir. Anlık geri bildirim gerektiren senaryolarda (örneğin checkout anında stok kontrolü) bulk operations uygun değildir; bu senaryolarda standart API çağrıları, rate limit’e dikkat edilerek kullanılmaya devam etmelidir.

Stok Senkronizasyon Hatalarını Önlemek İçin Hangi Mimari Kurulmalı?

Çoklu kanal stok senkronizasyonunda en sağlam mimari, her kanaldan gelen güncellemenin doğrudan Shopify API’sine gönderilmediği, önce merkezi bir kuyruğa (queue) yazılıp oradan kontrollü bir hızda işlendiği yapıdır. Bu mimari, rate limit kovasının doluluğunu tek bir noktadan yönetmeyi mümkün kılar.

Kuyruk tabanlı mimaride, pazaryeri webhook’u veya ERP’den gelen her stok değişikliği önce kuyruğa eklenir; ayrı bir işlemci (worker) bu kuyruktan saniyede belirli sayıda kaydı alıp Shopify API’sine gönderir ve Retry-After header’ını izleyerek hızını otomatik ayarlar. Bu yapı, kaynak sayısı arttıkça (yeni bir pazaryeri eklendiğinde) sadece kuyruğa yeni bir üretici eklemeyi gerektirir, mevcut rate limit yönetim mantığı değişmez.

Kritik Not: Doğrudan API entegrasyonu (her kaynak sistemin kendi kod tabanından Shopify’a istek atması) 2-3 kaynaklı entegrasyonlarda çalışabilir, ancak 4’ten fazla kaynak sisteme çıkıldığında merkezi kuyruk mimarisine geçilmeden rate limit sorunları kronikleşir.

Bir mağazanın Kasım kampanya döneminde 3 pazaryeri ve 1 ERP’den eşzamanlı gelen stok güncellemeleri, kuyruk mimarisi olmadan saatte binlerce isteğe ulaşabilir; bu hacim standart mağaza kovasının kapasitesinin çok üzerindedir ve kuyruksuz bir mimaride güncellemelerin büyük kısmı 429 hatasıyla kaybolur.

Rate Limit Hataları İzlenirken Hangi Metrikler Takip Edilmeli?

Rate limit sorunlarının kronikleşmesini önlemek için üç metrik sürekli izlenmelidir: 429 hata oranı, ortalama kova doluluk yüzdesi ve retry kuyruğunda bekleyen istek sayısı. Bu üç metrik birlikte okunduğunda, sorunun geçici bir yoğunluk mu yoksa yapısal bir kapasite açığı mı olduğu ayırt edilebilir.

429 hata oranının toplam istek sayısına oranı yüzde 1’i aştığında, bu genelde tekil bir yoğunluk anından değil sistematik bir tasarım sorunundan kaynaklanır. Ortalama kova doluluğu sürekli yüzde 80’in üzerinde seyrediyorsa, entegrasyonun istek hızı mağazanın kapasitesine çok yakın çalışıyor demektir ve küçük bir trafik artışı hemen 429 hatasına dönüşür.

Quotable: Kova doluluğu sürekli yüzde 80 üzerinde seyreden bir entegrasyon, kapasite sınırında çalışıyor demektir; bu durumda bir sonraki kampanya dönemi rate limit krizini neredeyse garantiler.

Retry kuyruğunda bekleyen istek sayısının zamanla artması, sistemin ürettiği isteklerin işlenme hızından daha büyük bir hızda birikmesi anlamına gelir; bu durum fark edilmezse kuyruk sürekli büyür ve stok verisi gitgide daha eski hale gelir. Bu üç metriğin bir izleme panosunda (dashboard) günlük olarak takip edilmesi, sorunu müşteri şikayeti haline gelmeden tespit etmeyi mümkün kılar.

Bu izleme disiplinini kuran bir ekip, kampanya öncesi kapasite planlaması yapabilir; örneğin Kasım kampanyasından iki hafta önce senkronizasyon sıklığını geçici olarak düşürüp kuyruk mimarisinin yükü kaldırıp kaldıramadığını test edebilir. Bu tür bir ön test, kampanya günü yaşanacak bir stok senkronizasyon krizini büyük ölçüde önler.

Shopify’dan Rate Limit Artırımı Talep Edilebilir mi?

Standart rate limit değerleri Shopify Plus dışındaki mağazalarda sabittir ve Shopify Support üzerinden bireysel bir artırım talebi genellikle kabul edilmez; kapasite artışı, mağazanın Shopify Plus planına geçmesiyle otomatik olarak gelir. Bu nedenle rate limit sorununu “daha fazla kapasite istemek” yerine mevcut kapasiteyi verimli kullanmakla çözmek gerekir.

Bazı uygulama geliştiricileri, Shopify Partner ekibiyle görüşerek belirli bir uygulama için özel bir limit artırımı talep edebilir; ancak bu süreç yalnızca Shopify App Store’da dağıtılan, çok sayıda mağazaya hizmet veren uygulamalar için değerlendirilir ve tek mağazalık custom app’lerde bu yol genelde kapalıdır. Gerçekçi çözüm yolu, GraphQL’e geçiş, bulk operations kullanımı ve kuyruk tabanlı mimari gibi mevcut araçları doğru sırayla uygulamaktır.

İpucu: Rate limit sorunuyla karşılaşan bir mağaza önce “kapasite artırımı” değil “istek verimliliği” sorusunu sormalı: Aynı işi daha az istekle (GraphQL, bulk operations) veya daha kontrollü bir hızda (kuyruk mimarisi) yapmanın yolu var mı? Çoğu durumda cevap evettir ve maliyeti Shopify Plus’a geçmekten çok daha düşüktür.

Bu gerçekçi yaklaşım, özellikle henüz Shopify Plus’a geçecek hacme ulaşmamış büyüyen mağazalar için önemlidir; mimari verimlilik, plan yükseltmesinden önce denenmesi gereken ilk adımdır.

Sık Sorulan Sorular

Shopify API rate limit aşıldığında mağaza kapanır mı? Hayır, mağaza kapanmaz; sadece rate limit’i aşan API isteği 429 durum koduyla reddedilir. Mağazanın kendi işleyişi (sipariş alma, ödeme işleme) bu durumdan etkilenmez, yalnızca entegrasyon isteği başarısız olur.

Shopify Plus mağazalarında rate limit farklı mı? Evet, Shopify Plus mağazaları standart mağazalara göre daha yüksek kova kapasitesine ve GraphQL maliyet havuzuna sahiptir. Tam kapasite değeri, mağaza planına ve Shopify ile yapılan anlaşmaya göre değişebilir.

Stok senkronizasyon hatası nasıl anlaşılır? En belirgin işaret, bir kanalda güncellenen stoğun diğer kanala geç veya hiç yansımamasıdır. API loglarında 429 durum kodlu isteklerin sıklığı kontrol edilerek kök neden doğrulanabilir.

Bulk Operations API her senaryoda kullanılabilir mi? Hayır, asenkron çalıştığı için anlık yanıt gerektiren senaryolarda (örneğin checkout sırasında stok kontrolü) uygun değildir. Toplu ve zaman kritik olmayan güncellemeler için idealdir.

Rate limit sorunu tek bir uygulamadan mı kaynaklanır, yoksa tüm mağaza için mi geçerlidir? Rate limit kovası her uygulama ve mağaza kombinasyonu için ayrı ayrı hesaplanır. Bir uygulamanın kovası dolsa bile aynı mağazadaki başka bir uygulamanın kovası bundan etkilenmez.

GraphQL’e geçmek rate limit sorununu tamamen çözer mi? Hayır, GraphQL farklı bir limit modeli kullanır ama sınırsız değildir; derin ve karmaşık sorgular GraphQL’in kendi maliyet havuzunu da hızla tüketebilir. Sorgu tasarımı ve sayfalama stratejisi GraphQL’de de dikkatli planlanmalıdır.

Rate limit hatası ile sunucu hatası (500) nasıl ayırt edilir? Rate limit hatası her zaman 429 durum kodu ve Retry-After header’ı ile gelir, bu ikisi birlikte görüldüğünde kaynak kesin olarak rate limit’tir. 500 durum kodu ise Shopify tarafında geçici bir sunucu sorununu işaret eder ve farklı bir retry stratejisi gerektirir.

Bir uygulama birden fazla mağazayı yönetiyorsa rate limit nasıl paylaşılır? Her mağaza kendi ayrı kovasına veya maliyet havuzuna sahiptir; bir mağazanın limiti dolsa bile aynı uygulamanın yönettiği başka bir mağazanın kovası bundan etkilenmez. Çoklu mağaza yöneten uygulamalar, her mağaza için ayrı bir rate limit takip mekanizması kurmalıdır, tek bir global sayaç yanlış sonuç üretir.

Sonraki Adım

Rate limit ve stok senkronizasyon sorunlarının çoğu, webhook tabanlı bir mimariyle önlenebilir; polling yerine olay bazlı bildirim kullanmak gereksiz API çağrısını baştan ortadan kaldırır. Webhook kurulumunun teknik adımları Shopify webhook kurulumu rehberinde, genel API mimarisi kararları ise Shopify özel API ve app entegrasyonu rehberinde ele alınır. Çoklu kanal senkronizasyonuna özel mimari kararlar için Shopify pazaryeri entegrasyonu rehberi ve Shopify ERP ve muhasebe entegrasyonu rehberleri sonraki adım olarak incelenebilir.