Limites de débit et codes d'erreur MCP
Limites sans clé de 10 requêtes par minute et 200 par jour par IP, 60 par minute avec une clé gratuite, et les erreurs 401, 403, 429 et 503 possibles.
Sur cette page
Limites de débit
Deux niveaux. Aucun compte ni aucune clé n’est nécessaire : sans clé, vous êtes au niveau sans clé ; une clé gratuite (Démarrage) vous fait passer au niveau avec clé.
| Sans clé | Avec une clé gratuite | |
|---|---|---|
| Appels d’outil | 10 par minute et 200 par jour, par adresse IP | 60 requêtes par minute, par clé |
| Connexion et liste des outils | Gratuites ; plafond anti-saturation de 60 par minute par IP | Comptées dans les 60 |
shamela_read (unit: 'range') | Jusqu’à 5 pages par appel | Jusqu’à 20 |
shamela_read (unit: 'section') | Jusqu’à 10 pages par appel | Jusqu’à 100 |
Toutes les fenêtres sont glissantes. Un appel refusé ne consomme rien — atteindre la limite par minute n’entame pas la limite quotidienne.
Les limites sans clé sont comptées par adresse IP, faute de mieux. Tous les appelants sans clé partagent aussi un même pool de capacité : à un moment chargé, un appel sans clé peut donc être refusé avant que vous atteigniez votre propre limite ; l’erreur le précise. Une plage de pages plus courte n’est pas une page perdue : la réponse indique où continuer.
Les limites avec clé sont comptées par clé, pas par adresse IP. Les clients MCP se trouvent souvent derrière des réseaux partagés, et chaque recherche s’exécute sur un service de bibliothèque partagé : le coût est donc réel, d’où que vienne la requête.
Chaque réponse porte l’état courant :
| En-tête | Signification |
|---|---|
ratelimit-limit | Le plafond le plus proche d’être atteint. |
ratelimit-remaining | Requêtes restantes sous ce plafond. |
ratelimit-reset | Secondes avant la réinitialisation de sa fenêtre. |
Si vous dépassez une limite, vous recevez 429 avec un en-tête retry-after et un message qui nomme la limite atteinte. Attendez ce délai et reprenez — ou, si le message concerne le niveau sans clé, ajoutez une clé.
Un appel à
shamela_search_librarycompte pour une requête sur votre limite, même s’il exécute éventuellement deux passes en interne.
Les quatre erreurs à gérer
Une requête sans clé n’est jamais refusée faute de clé. Une clé envoyée est vérifiée, et une mauvaise est refusée plutôt que traitée discrètement comme sans clé — sinon vous n’apprendriez jamais qu’elle a cessé de fonctionner.
Chaque corps d’erreur est une erreur JSON-RPC avec id: null ; le code indique donc de quel cas il s’agit même lorsque le statut est masqué.
| Statut | Code JSON-RPC | Signification | Que faire |
|---|---|---|---|
| 401 | -32001 | Une clé a été envoyée et n’est pas valide. | Vérifiez l’en-tête Authorization: Bearer …. Si la clé a été supprimée, créez-en une nouvelle — ou retirez l’en-tête pour continuer au niveau sans clé. |
| 403 | -32003 | La clé est valide mais ne peut pas utiliser le serveur : son compte est suspendu. | Voir Comptes bannis. |
| 429 | -32004 | Une limite de débit a été atteinte ; le message précise laquelle. L’en-tête Retry-After indique combien de secondes attendre. | Attendez, puis réessayez. Les appelants sans clé peuvent aussi ajouter une clé gratuite. |
| 503 | -32002 | Votre clé n’a pas pu être vérifiée pour le moment ; la requête a donc été refusée plutôt que laissée passer. | Transitoire. Réessayez après l’en-tête Retry-After (30 secondes). |
Un 503 signifie que le serveur n’a pas pu confirmer la validité de votre clé ; il a donc refusé la requête plutôt que de deviner. Il n’admet jamais une clé invérifiable — une requête qui ne peut pas être authentifiée est rejetée, pas laissée passer.
Requêtes mal formées et pannes du serveur
Outre ces quatre-là, le serveur n’envoie que celles-ci, qu’un client MCP normal ne déclenche jamais :
| Statut | Code JSON-RPC | Signification | Que faire |
|---|---|---|---|
| 400 | -32700 | Le corps n’est pas du JSON valide. | Corrigez la requête ; la renvoyer telle quelle échoue de la même façon. |
| 400 | -32600 | Le corps est du JSON mais pas une requête JSON-RPC 2.0 (jsonrpc: "2.0" ou method manquant, ou un lot). | Envoyez une requête par POST — MCP 2025-06-18 n’a pas de traitement par lots. |
| 500 | -32603 | Une panne inattendue côté serveur. | Réessayez une fois après quelques secondes ; si elle persiste, la panne est de notre côté. |
Un 502 ou 504 ne vient pas du serveur MCP — il vient du proxy placé devant lui pendant que le serveur redémarre ou est injoignable. Traitez-le comme un 500 et réessayez peu après.
Deux sortes d’échec
Une fois authentifié, les échecs arrivent sous deux formes, et la différence est voulue.
Une erreur d’outil revient comme un résultat normal marqué isError, avec un message que votre assistant peut lire et exploiter. Envoyez une portée invalide et la liste des portées valides vous est renvoyée, de sorte que le modèle peut simplement réessayer avec une vraie portée :
scope is required and must be one of: hadith-primary, tafsir-canonical, fiqh-hanafi, …
Une erreur de protocole revient comme une erreur JSON-RPC, pour les problèmes que votre assistant ne peut pas corriger en réessayant — demander un outil qui n’existe pas, ou envoyer une requête mal formée.
| Situation | Forme |
|---|---|
scope manquante ou invalide | Erreur d’outil (isError) |
query vide | Erreur d’outil (isError) |
| La bibliothèque décroche pendant un appel | Erreur d’outil (isError) |
| Bibliothèque déjà injoignable au moment de l’appel | Erreur de protocole -32601 (voir ci-dessous) |
| Nom d’outil inconnu | Erreur de protocole -32601 |
| Requête JSON-RPC mal formée | Erreur de protocole -32600 |
Cette séparation compte parce que beaucoup de clients ne montrent jamais une erreur de protocole au modèle — il voit simplement l’appel échouer. Mettre les erreurs récupérables dans le résultat permet à un assistant de se corriger au lieu d’abandonner.
Quand la bibliothèque est indisponible
Si le service de bibliothèque est injoignable, tools/list renvoie aucun outil plutôt que d’en annoncer un qui échouerait en plein appel, et toute tentative d’appel renvoie l’erreur de protocole -32601 avec un message indiquant que la bibliothèque est temporairement injoignable. C’est un HTTP 200, pas un 503.
C’est pourquoi un client qui liste soudain zéro outil vous montre un vrai signal, pas un problème de configuration. Laissez-lui une minute et reconnectez-vous.
Perdre une clé
Les clés ne se récupèrent pas — seul un hachage est conservé. Si vous en perdez une ou pensez qu’elle a fuité, supprimez-la d’abord, puis créez un remplacement. Supprimer d’abord ferme la fenêtre pendant laquelle quelqu’un d’autre détient une clé fonctionnelle.
La révocation peut prendre jusqu’à 60 secondes pour atteindre ce point d’accès. Les clés vérifiées sont mises en cache pendant une minute afin que chaque appel d’outil n’exige pas un aller-retour vers le service des comptes. Une clé que vous venez de supprimer peut continuer à fonctionner jusqu’à la fin de cette minute — mesuré à environ 6 secondes en pratique, mais prévoyez 60.
Cette fenêtre compte quand vous révoquez une clé compromise plutôt que de faire du rangement. Supprimez-la immédiatement malgré tout ; puis considérez la minute suivante comme encore exposée plutôt que de supposer que la porte s’est fermée à l’instant du clic.
La gestion complète des clés est traitée dans Clés d’API.