Batas laju MCP dan kode galat
Batas tanpa kunci 10 permintaan per menit dan 200 per hari per IP, 60 per menit dengan kunci gratis, serta galat 401, 403, 429, dan 503.
Di halaman ini
Batas laju
Dua tingkat. Tidak perlu akun atau kunci: tanpa kunci Anda berada di tingkat tanpa kunci; kunci gratis (Memulai) memindahkan Anda ke tingkat berkunci.
| Tanpa kunci | Dengan kunci gratis | |
|---|---|---|
| Panggilan alat | 10 per menit dan 200 per hari, per alamat IP | 60 permintaan per menit, per kunci |
| Menyambung dan menampilkan daftar alat | Gratis; batas banjir 60 per menit per IP | Dihitung dalam 60 |
shamela_read (unit: 'range') | Hingga 5 halaman per panggilan | Hingga 20 |
shamela_read (unit: 'section') | Hingga 10 halaman per panggilan | Hingga 100 |
Semua jendela bersifat bergeser (sliding). Panggilan yang ditolak tidak memakai jatah — menyentuh batas per menit tidak mengurangi batas harian.
Batas tanpa kunci dihitung per alamat IP, karena tidak ada hal lain yang bisa dihitung. Semua pemanggil tanpa kunci juga berbagi satu kolam kapasitas, sehingga pada saat ramai sebuah panggilan tanpa kunci bisa ditolak sebelum Anda mencapai batas Anda sendiri; galatnya menyatakan hal itu. Rentang halaman yang lebih pendek bukan halaman yang hilang: respons memberi tahu dari mana melanjutkan.
Batas berkunci dihitung terhadap kunci, bukan alamat IP Anda. Klien MCP sering berada di balik jaringan bersama, dan setiap pencarian berjalan terhadap layanan perpustakaan bersama, jadi biayanya nyata di mana pun permintaan itu berasal.
Setiap respons membawa keadaan terkini:
| Header | Arti |
|---|---|
ratelimit-limit | Batas yang paling dekat untuk tercapai. |
ratelimit-remaining | Sisa permintaan di bawah batas itu. |
ratelimit-reset | Detik sampai jendelanya direset. |
Bila melampaui batas, Anda mendapat 429 dengan header retry-after dan pesan yang menyebut batas mana yang tercapai. Tunggu selama itu lalu lanjutkan — atau, bila pesannya tentang tingkat tanpa kunci, tambahkan kunci.
Satu panggilan
shamela_search_libraryadalah satu permintaan terhadap batas Anda, meski secara internal ia mungkin menjalankan dua putaran.
Empat galat yang perlu ditangani
Permintaan tanpa kunci tidak pernah ditolak karena tidak punya kunci. Kunci yang dikirim akan diperiksa, dan kunci yang buruk ditolak, bukan diam-diam diperlakukan sebagai tanpa kunci — jika tidak, Anda tidak akan pernah tahu bahwa kunci itu sudah berhenti bekerja.
Setiap isi galat adalah galat JSON-RPC dengan id: null, sehingga kodenya memberi tahu kasus mana yang Anda alami meski statusnya tersembunyi.
| Status | Kode JSON-RPC | Arti | Yang dilakukan |
|---|---|---|---|
| 401 | -32001 | Sebuah kunci dikirim dan tidak valid. | Periksa header Authorization: Bearer …. Bila kunci telah dihapus, buat yang baru — atau hapus header untuk melanjutkan di tingkat tanpa kunci. |
| 403 | -32003 | Kunci valid tetapi tidak boleh memakai server: akunnya ditangguhkan. | Lihat Akun yang diblokir. |
| 429 | -32004 | Sebuah batas laju tercapai; pesan menyebut yang mana. Header Retry-After menyebut berapa detik menunggu. | Tunggu, lalu coba lagi. Pemanggil tanpa kunci juga bisa menambahkan kunci gratis. |
| 503 | -32002 | Kunci Anda tidak dapat diverifikasi saat ini, sehingga permintaan ditolak alih-alih diloloskan. | Sementara. Coba lagi setelah header Retry-After (30 detik). |
503 berarti server tidak bisa memastikan kunci Anda valid, sehingga ia menolak permintaan alih-alih menebak. Ia tidak pernah menerima kunci yang tidak dapat diverifikasi — permintaan yang tidak dapat diautentikasi ditolak, bukan diloloskan.
Permintaan cacat dan kesalahan server
Selain keempat itu, server hanya mengirim yang berikut, yang tidak pernah dipicu klien MCP biasa:
| Status | Kode JSON-RPC | Arti | Yang dilakukan |
|---|---|---|---|
| 400 | -32700 | Isi bukan JSON yang valid. | Perbaiki permintaan; mengulanginya tanpa perubahan gagal dengan cara yang sama. |
| 400 | -32600 | Isi berupa JSON tetapi bukan permintaan JSON-RPC 2.0 (tanpa jsonrpc: "2.0" atau method, atau berupa batch). | Kirim satu permintaan per POST — MCP 2025-06-18 tidak mengenal batching. |
| 500 | -32603 | Kesalahan tak terduga di server. | Coba lagi sekali setelah beberapa detik; bila berlanjut, kesalahannya ada pada kami. |
502 atau 504 tidak berasal dari server MCP — ia berasal dari proxy di depannya saat server dimulai ulang atau tidak terjangkau. Perlakukan seperti 500 dan coba lagi sebentar lagi.
Dua jenis kegagalan
Setelah Anda terautentikasi, kegagalan datang dalam salah satu dari dua bentuk, dan perbedaannya disengaja.
Galat alat datang sebagai hasil normal bertanda isError, dengan pesan yang bisa dibaca dan ditindaklanjuti asisten Anda. Kirim cakupan yang tidak valid dan Anda mendapat daftar yang valid, sehingga model cukup mencoba ulang dengan cakupan sungguhan:
scope is required and must be one of: hadith-primary, tafsir-canonical, fiqh-hanafi, …
Galat protokol datang sebagai galat JSON-RPC, untuk masalah yang tidak bisa diperbaiki asisten Anda dengan mencoba lagi — meminta alat yang tidak ada, atau mengirim permintaan cacat.
| Situasi | Bentuk |
|---|---|
scope hilang atau tidak valid | Galat alat (isError) |
query kosong | Galat alat (isError) |
| Perpustakaan terputus di tengah panggilan | Galat alat (isError) |
| Perpustakaan sudah tidak terjangkau saat Anda memanggil | Galat protokol -32601 (lihat di bawah) |
| Nama alat tidak dikenal | Galat protokol -32601 |
| Permintaan JSON-RPC cacat | Galat protokol -32600 |
Pemisahan ini penting karena banyak klien tidak pernah menampilkan galat protokol kepada model — ia hanya melihat panggilan gagal. Menaruh kesalahan yang bisa dipulihkan dalam hasil adalah yang membuat asisten bisa mengoreksi dirinya, bukan menyerah.
Bila perpustakaan tidak tersedia
Bila layanan perpustakaan tidak terjangkau, tools/list mengembalikan nol alat alih-alih mengiklankan alat yang akan gagal di tengah panggilan, dan setiap panggilan yang dicoba mengembalikan galat protokol -32601 dengan pesan yang menyatakan perpustakaan sementara tidak terjangkau. Ini HTTP 200, bukan 503.
Inilah sebabnya klien yang tiba-tiba menampilkan nol alat sedang menunjukkan sinyal nyata, bukan masalah konfigurasi. Beri waktu semenit lalu sambungkan ulang.
Kehilangan kunci
Kunci tidak bisa dipulihkan — hanya hash-nya yang disimpan. Bila Anda kehilangannya atau mengira ia bocor, hapus dulu, lalu buat penggantinya. Menghapus lebih dulu menutup celah di mana orang lain memegang kunci yang masih berfungsi.
Pencabutan butuh hingga 60 detik untuk sampai ke endpoint ini. Kunci yang sudah diverifikasi disimpan di cache selama semenit agar setiap panggilan alat tidak memerlukan perjalanan bolak-balik ke layanan akun. Kunci yang baru Anda hapus bisa tetap berfungsi sampai menit itu habis — terukur sekitar 6 detik dalam praktik, tetapi rencanakan 60.
Celah itu penting ketika Anda mencabut kunci yang bocor, bukan sekadar merapikan. Hapus segera bagaimanapun; lalu anggap menit berikutnya masih terbuka, jangan mengira pintu tertutup begitu Anda mengklik.
Pengelolaan kunci selengkapnya dibahas di Kunci API.