T-SOFT/Admin API/Hız sınırları

Hız sınırları

Admin API, her uygulamanın bir mağazaya gönderebileceği istek sayısını sınırlar. Sınırı aşan istek 429 döner; yanıt başlıkları kalan hakkınızı ve ne kadar beklemeniz gerektiğini söyler.

Uygulama başına sınır

Her uygulama, kurulu olduğu her mağazaya dakikada 120 istek gönderebilir. Bu, saniyede ortalama 2 istektir.

  • Sayaç uygulamaya ve mağazaya aittir. Aynı mağazada yeni token almak sayacı sıfırlamaz; uygulamanızın o mağazadaki bütün token'ları aynı sayacı doldurur.
  • Her mağazanın sayacı ayrıdır. Uygulamanızın bir mağazadaki yoğunluğu başka bir mağazayı etkilemez.
  • Sayaç dakikalık pencerelerle tutulur. Pencere dolduğunda, yanıttaki Retry-After süresi kadar sonra yeni pencere açılır.

Uç noktaya özel sınırlar

Bazı uç noktaların uygulama sınırına ek olarak kendi sınırı vardır. İkisi birlikte uygulanır; hangisi önce dolarsa 429 döner.

Müşteri davetlerinin ayrıca mağaza başına saatlik sınırı vardır; ayrıntısı Müşteriler sayfasındadır.

Yanıt başlıkları

Sınırı olan her yanıt şu başlıkları taşır:

BaşlıkNe
X-RateLimit-LimitBu istekte geçerli olan sınır
X-RateLimit-RemainingPencere dolmadan önce kalan istek hakkı

Bir istekte birden fazla sınır geçerliyse başlıklar en az hakkı kalan sınırı gösterir. X-RateLimit-Remaining değerine göre hız ayarlarsanız 429 almazsınız.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87

Sınır aşıldığında

Sınırı aşan istek işlenmez ve 429 döner. Yanıtta iki başlık daha vardır:

BaşlıkNe
Retry-AfterYeniden denemeden önce beklemeniz gereken saniye
X-RateLimit-ResetPencerenin açılacağı an, Unix saniye
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 42
X-RateLimit-Reset: 1794763199

Gövde, diğer hatalar gibi JSON:API hata biçimindedir:

{
  "jsonapi": { "version": "1.0" },
  "errors": [
    {
      "status": "429",
      "title": "Too Many Requests",
      "detail": "Too Many Attempts."
    }
  ]
}

Retry-After kadar bekleyip isteği aynen tekrarlayın. Beklemeden yeniden denemek sayacı açmaz; yalnız yeni 429 yanıtları üretir.

İyi uygulamalar

  • Kalan hakkı izleyin. X-RateLimit-Remaining azaldıkça istekleri yavaşlatın; sıfıra inmesini beklemeyin.
  • Paralel isteği sınırlayın. Aynı mağazaya aynı anda çok sayıda istek göndermek yerine istekleri bir kuyruğa alın.
  • Toplu uç noktaları kullanın. Toplu işlem sunan kaynaklarda (ör. yönlendirmeler) kayıtları tek tek göndermek yerine toplu uç noktayı kullanın.
  • Sorgulama yerine webhook kullanın. Bir kaydın değişip değişmediğini düzenli aralıklarla sormak yerine webhook'lara abone olun.
  • Sayfa boyutunu büyütün. Listeleme isteklerinde page[size] değerini artırarak daha az istekle aynı veriyi alın (Sorgu parametreleri).
  • Token'ı saklayın. Her istekten önce yeni token almayın; token'ı süresi dolana kadar kullanın.