MCP hız sınırları ve hata kodları
IP başına dakikada 10 ve günde 200 anahtarsız istek, ücretsiz anahtarla dakikada 60 ve alabileceğiniz 401, 403, 429 ve 503 hataları.
Bu sayfada
Hız sınırları
İki katman. Hesap veya anahtar gerekmez: anahtarsız kullanımda anahtarsız katmandasınız; ücretsiz bir anahtar (Başlangıç) sizi anahtarlı katmana taşır.
| Anahtarsız | Ücretsiz anahtarla | |
|---|---|---|
| Araç çağrıları | IP adresi başına dakikada 10 ve günde 200 | Anahtar başına dakikada 60 istek |
| Bağlanma ve araçları listeleme | Ücretsiz; IP başına dakikada 60’lık bir taşkın tavanı | 60’a dahil sayılır |
shamela_get_pages_range | Çağrı başına en fazla 5 sayfa | En fazla 20 |
shamela_get_book_section | Çağrı başına en fazla 10 sayfa | En fazla 100 |
Tüm pencereler kayan penceredir. Reddedilen bir çağrı hiçbir şey harcamaz — dakikalık sınıra takılmak günlük sınırdan yemez.
Anahtarsız sınırlar IP adresi başına sayılır, çünkü sayılacak başka bir şey yoktur. Tüm anahtarsız çağıranlar ayrıca tek bir kapasite havuzunu paylaşır; bu yüzden yoğun bir anda anahtarsız bir çağrı kendi sınırınıza ulaşmadan reddedilebilir; hata bunu belirtir. Daha kısa bir sayfa aralığı kayıp bir sayfa değildir: yanıt nereden devam edileceğini söyler.
Anahtarlı sınırlar IP adresinize değil anahtara karşı sayılır. MCP istemcileri sıklıkla paylaşımlı ağların arkasındadır ve her arama paylaşımlı bir kütüphane servisine karşı çalışır; dolayısıyla isteğin nereden geldiğinden bağımsız olarak maliyet gerçektir.
Her yanıt güncel durumu taşır:
| Başlık | Anlamı |
|---|---|
ratelimit-limit | Ulaşılmaya en yakın tavan. |
ratelimit-remaining | O tavan altında kalan istekler. |
ratelimit-reset | Penceresinin sıfırlanmasına kalan saniye. |
Bir sınırı aşarsanız retry-after başlığı ve hangi sınıra takıldığınızı belirten bir mesajla 429 alırsınız. O kadar bekleyin ve devam edin — ya da mesaj anahtarsız katmanla ilgiliyse bir anahtar ekleyin.
Dahili olarak iki geçiş çalıştırabilse de bir
search_libraryçağrısı, sınırınıza karşı bir istektir.
Ele alınması gereken dört hata
Anahtarı olmayan bir istek, anahtarı olmadığı için asla reddedilmez. Gönderilen bir anahtar denetlenir ve kötü bir anahtar sessizce anahtarsız sayılmak yerine reddedilir — aksi halde çalışmayı bıraktığını asla öğrenemezdiniz.
Her hata gövdesi id: null içeren bir JSON-RPC hatasıdır; böylece durum gizlense bile kod hangi durumla karşılaştığınızı söyler.
| Durum | JSON-RPC kodu | Anlamı | Ne yapmalı |
|---|---|---|---|
| 401 | -32001 | Bir anahtar gönderildi ve geçerli değil. | Authorization: Bearer … başlığını kontrol edin. Anahtar silindiyse yeni bir tane oluşturun — ya da anahtarsız katmanda devam etmek için başlığı kaldırın. |
| 403 | -32003 | Anahtar geçerli ama sunucuyu kullanamaz: hesabı askıya alınmış. | Bkz. Yasaklı hesaplar. |
| 429 | -32004 | Bir hız sınırına ulaşıldı; mesaj hangisi olduğunu söyler. Retry-After başlığı kaç saniye bekleneceğini söyler. | Bekleyin, sonra yeniden deneyin. Anahtarsız çağıranlar ücretsiz bir anahtar da ekleyebilir. |
| 503 | -32002 | Anahtarınız şu anda doğrulanamadı, bu yüzden istek geçirilmek yerine reddedildi. | Geçici. Retry-After başlığındaki süreden (30 saniye) sonra yeniden deneyin. |
Bir 503, sunucunun anahtarınızın geçerli olduğunu doğrulayamadığı anlamına gelir; bu yüzden tahmin yürütmek yerine isteği reddetti. Doğrulanamayan bir anahtarı asla kabul etmez — kimliği doğrulanamayan bir istek geçirilmez, reddedilir.
Hatalı biçimli istekler ve sunucu arızaları
Bu dördünün dışında sunucu yalnızca şunları gönderir; normal bir MCP istemcisi bunları asla tetiklemez:
| Durum | JSON-RPC kodu | Anlamı | Ne yapmalı |
|---|---|---|---|
| 400 | -32700 | Gövde geçerli JSON değil. | İsteği düzeltin; değiştirmeden yeniden denemek aynı şekilde başarısız olur. |
| 400 | -32600 | Gövde JSON ama JSON-RPC 2.0 isteği değil (jsonrpc: "2.0" veya method eksik, ya da bir toplu istek). | POST başına tek istek gönderin — MCP 2025-06-18’de toplu istek yoktur. |
| 500 | -32603 | Sunucuda beklenmeyen bir arıza. | Birkaç saniye sonra bir kez yeniden deneyin; sürerse arıza bizdedir. |
Bir 502 veya 504, MCP sunucusundan gelmez — sunucu yeniden başlarken veya ulaşılamazken önündeki proxy’den gelir. Onu bir 500 gibi ele alın ve kısa süre sonra yeniden deneyin.
İki tür başarısızlık
Kimliğiniz doğrulandıktan sonra başarısızlıklar iki biçimden biriyle gelir ve fark bilinçlidir.
Bir araç hatası, asistanınızın okuyup üzerine hareket edebileceği bir mesajla, isError olarak işaretlenmiş normal bir sonuç olarak gelir. Geçersiz bir kapsam gönderirseniz geçerli olanların listesi geri döner; böylece model gerçek bir kapsamla yeniden deneyebilir:
scope is required and must be one of: hadith-primary, tafsir-canonical, fiqh-hanafi, …
Bir protokol hatası, asistanınızın yeniden deneyerek düzeltemeyeceği sorunlar için — var olmayan bir araç istemek veya hatalı biçimli bir istek göndermek — JSON-RPC hatası olarak gelir.
| Durum | Biçim |
|---|---|
Eksik veya geçersiz scope | Araç hatası (isError) |
Boş query | Araç hatası (isError) |
| Kütüphane çağrı sırasında kopuyor | Araç hatası (isError) |
| Siz çağırdığınızda kütüphaneye zaten ulaşılamıyor | Protokol hatası -32601 (aşağıya bakın) |
| Bilinmeyen araç adı | Protokol hatası -32601 |
| Hatalı biçimli JSON-RPC isteği | Protokol hatası -32600 |
Bu ayrım önemlidir, çünkü birçok istemci protokol hatasını modele hiç göstermez — model yalnızca çağrının başarısız olduğunu görür. Düzeltilebilir hataları sonucun içine koymak, bir asistanın pes etmek yerine kendini düzeltmesini sağlar.
Kütüphane kullanılamadığında
Kütüphane servisine ulaşılamıyorsa tools/list, çağrının ortasında başarısız olacak bir aracı duyurmak yerine hiç araç döndürmez ve denenen her çağrı, kütüphaneye geçici olarak ulaşılamadığını söyleyen -32601 protokol hatası döndürür. Bu HTTP 200’dür, 503 değil.
Bu yüzden birden sıfır araç listeleyen bir istemci, yapılandırma sorunu değil gerçek bir sinyal gösteriyordur. Bir dakika verin ve yeniden bağlanın.
Anahtarı kaybetmek
Anahtarlar kurtarılamaz — yalnızca bir özet (hash) saklanır. Birini kaybettiyseniz veya sızdığını düşünüyorsanız önce silin, sonra yerine yenisini oluşturun. Önce silmek, bir başkasının çalışan bir anahtara sahip olduğu aralığı kapatır.
İptalin bu uç noktaya ulaşması 60 saniyeye kadar sürer. Doğrulanmış anahtarlar bir dakika önbelleğe alınır; böylece her araç çağrısı hesap servisine gidiş-dönüş gerektirmez. Az önce sildiğiniz bir anahtar o dakika dolana kadar çalışmaya devam edebilir — pratikte ~6 saniye ölçüldü, ama 60 için plan yapın.
Bu aralık, düzen yapmak yerine sızmış bir anahtarı iptal ederken önemlidir. Yine de hemen silin; ardından tıkladığınız anda kapının kapandığını varsaymak yerine sonraki dakikayı hâlâ açıkta sayın.
Anahtar yönetiminin tamamı API anahtarları sayfasında ele alınır.