Kotalar ve hız sınırları

Yapabileceklerinizi birbirinden bağımsız iki şey sınırlar: planınızın günde kaç aramaya izin verdiği ve isteklerin hangi hızla gelebileceği. İkisi de her yanıtta bildirilir; böylece bir istemci, sınırların nerede olduğunu öğrenmek için bilerek hata almak zorunda kalmadan kendi hızını ayarlayabilir.

Hız sınırı: dakikada on istek

Sınır hesap başınadır ve API ile MCP sunucusu için ortaktır: hangi yoldan gelirse gelsin dakikada on çağrı. Bu süre içindeki on birinci istek hemen 429 too_many_requests ile geri döner; yanıttaki Retry-After başlığı, yeni bir isteğe yer açılmasına kaç saniye kaldığını bildirir. Aynı sayı gövdede error.retry_after olarak da yer alır.

HTTP/2 429
Retry-After: 18

{ "error": { "code": "too_many_requests",
             "message": "At most 10 requests per minute.",
             "retry_after": 18 } }

Retry-After başlığındaki saniye kadar bekleyin ve isteği tekrarlayın. Hiçbir şey tüketilmez, kotadan da bir şey harcanmaz.

API sizi yavaşlatmak için bağlantıyı hiçbir zaman açık tutmaz. Eski dışa aktarma URL'leri ise tutar: reddetmeden önce yarım dakikaya kadar saniye saniye bekler. API'nin var olma nedenlerinden biri de budur.

Günlük kota

Planınız günde belirli sayıda aramaya ve belirli sayıda parçacıklı isteğe izin verir; ikisi ayrı sayılır. İkisi de kullanımdan 24 saat sonra değil, bir sonraki UTC gece yarısında sıfırlanır.

Bir arama, arama kotasından bir düşer.
snippets=1 ile yapılan bir arama ise bunun yerine parçacık kotasından bir düşer.
/v1/account hiçbir şey harcamaz.

Bir kota bittiğinde istek 429 quota_exceeded ya da 429 snippet_quota_exceeded ile reddedilir; yanıtta sınır, kullanılan miktar ve sıfırlanmaya kalan süre yer alır. Parçacık kotasının bitmesi normal aramaları durdurmaz.

Sonuç derinliği

Plan ayrıca sonuçların sıralamada ne kadar aşağıya kadar gösterileceğini de belirler: /v1/account yanıtındaki disclosed_positions. Bu noktanın ötesindeki satırlar boş bırakılmaz, hiç verilmez; böyle satırlar olduğunda gövdede truncated alanı true, başlıklarda ise X-Truncated: true olur.

API ile web sitesi arasındaki en önemli fark budur. Kotası biten bir tarayıcı sessizce ücretsiz planın derinliğine geçer ve daha az sonuç gösterir; sayfaya bakan bir insan için bu sorun değildir. Bir betik bunun olduğunu göremez, bu yüzden API yanıtı kısaltmak yerine isteği reddeder.

Güncel durumu okuma

Kimliği doğrulanmış her yanıtta beş başlık bulunur:

Başlık	Anlamı
`X-RateLimit-Limit`	Bugün izin verilen arama sayısı.
`X-RateLimit-Remaining`	Bugün kalan arama sayısı.
`X-RateLimit-Reset`	Günlük kotanın sıfırlanacağı Unix zamanı.
`X-Snippets-Limit`	Bugün izin verilen parçacıklı istek sayısı.
`X-Snippets-Remaining`	Bugün kalan parçacıklı istek sayısı.

Sonuç yanıtlarında üç başlık daha vardır:

Başlık	Anlamı
`X-Total-Results`	Dizinin tamamında kaç sitenin eşleştiği.
`X-Returned-Results`	Bu yanıtta kaç satır olduğu.
`X-Truncated`	Planın derinlik sınırı satır çıkardığında `true`.

Kullanım istatistikleri

/v1/account tek çağrıda tüm tabloyu verir ve hiçbir şey harcamaz:

curl -H "Authorization: Bearer $KEY" https://api.publicwww.com/v1/account

{
  "plan": "enterprise",
  "plan_until": 1819461840,
  "full_access": true,
  "quota": {
    "searches": { "limit": 300, "used": 12, "resets_at": 1787961600 },
    "snippets": { "limit": 100, "used": 3,  "resets_at": 1787961600 }
  },
  "limits": {
    "disclosed_positions": 4294967295,
    "disclosed_positions_snippets": 4294967295,
    "max_per_page": 1000000,
    "max_per_page_snippets": 10000
  }
}

Eski https://publicwww.com/profile/api_status.xml?key=... adresi aynı sayaçları XML olarak bildirir ve hâlâ çalışır. Bu adres eski URL'lere aittir; yeni kodda, yalnızca sayıları değil sınırları da bildiren /v1/account uç noktasını kullanın.

Sonraki Hatalar