Hız sınırları ve önbellek

Adil kullanımı korumak için bazı uçlar istemci IP’si başına sabit zaman penceresiyle sınırlanır.

Uç grubu	Sınır
Hesaplama (`calculateByKey`, `calculateTool`; ortak sayılır)	60 istek / 60 sn
Arama (`searchTools`)	60 istek / 60 sn
Diğer okuma uçları (liste, kategori, tanım)	Önbellekli; ayrı sayaç yok
Gövde boyutu	En çok 16 KB (`413 PAYLOAD_TOO_LARGE`)
İstek süresi	15 sn (`504 TIMEOUT`)

Başlıklar

Sınırlı uçlar her yanıtta şunları döner (tarayıcıdan okunabilir):

RateLimit-Limit: 60
RateLimit-Remaining: 59

Sınır aşıldığında 429 RATE_LIMITED ve şu bilgiler gelir:

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

{ "error": { "code": "RATE_LIMITED", "message": "…", "details": { "retryAfterSeconds": 23 } }, "requestId": "…" }

Retry-After kadar bekleyin, sonra yeniden deneyin. Beklerken kullanıcıya “çok sık deneme yapıldı” gibi bir bilgi gösterin.

İstek sayısını azaltma

Tanımları önbelleğe alın. getToolByKey yanıtı kısa süre (max-age=5, CDN’de 30 sn, 5 dk stale-while-revalidate) önbelleklenir; kendi uygulamanızda dakikalar–saatler boyunca saklayabilirsiniz. Güncellik için hesaplamada version gönderin (Hesaplama).
Kategori ağacını bir kez alıp saklayın.
Aramada gecikme (debounce) kullanın: kullanıcı yazarken her tuşta değil, 250–400 ms sessizlikten sonra isteyin. Aynı sorguyu tekrar sormayın.
Hesaplamayı bir eylemle tetikleyin (buton, alan terk edildiğinde); her tuş vuruşunda hesaplamayın.
Aynı girdiler için sonucu önbelleğe alabilirsiniz: sonuçlar belirli araç sürümü, girdiler ve asOf için deterministiktir. Önbellek anahtarına toolVersion ve asOf değerini katın.
Toplu çekimler için (listAllTools) sayfalar arasında kısa bekleyin ve sonuçları kalıcı saklayın.

İstek kimliği

İstek kimliğinizi X-Request-Id ile gönderirseniz ([A-Za-z0-9._:-], 8–128 karakter) yanıtta aynen döner; kendi günlüklerinizle eşleştirmek için kullanışlıdır.

Yüksek hacim

Sürekli ve yüksek hacimli kullanım için bize ulaşın. Önbellekleme ve widget kullanımı çoğu entegrasyon için sınırlara takılmadan yeterlidir; widget hesaplamayı kullanıcının tarayıcısından yaptığı için yükü kullanıcılar arasında dağıtır.