Aller au contenu

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’outil10 par minute et 200 par jour, par adresse IP60 requêtes par minute, par clé
Connexion et liste des outilsGratuites ; plafond anti-saturation de 60 par minute par IPComptées dans les 60
shamela_read (unit: 'range')Jusqu’à 5 pages par appelJusqu’à 20
shamela_read (unit: 'section')Jusqu’à 10 pages par appelJusqu’à 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êteSignification
ratelimit-limitLe plafond le plus proche d’être atteint.
ratelimit-remainingRequêtes restantes sous ce plafond.
ratelimit-resetSecondes 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_library compte 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é.

StatutCode JSON-RPCSignificationQue faire
401-32001Une 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-32003La clé est valide mais ne peut pas utiliser le serveur : son compte est suspendu.Voir Comptes bannis.
429-32004Une 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-32002Votre 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 :

StatutCode JSON-RPCSignificationQue faire
400-32700Le corps n’est pas du JSON valide.Corrigez la requête ; la renvoyer telle quelle échoue de la même façon.
400-32600Le 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-32603Une 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.

SituationForme
scope manquante ou invalideErreur d’outil (isError)
query videErreur d’outil (isError)
La bibliothèque décroche pendant un appelErreur d’outil (isError)
Bibliothèque déjà injoignable au moment de l’appelErreur de protocole -32601 (voir ci-dessous)
Nom d’outil inconnuErreur de protocole -32601
Requête JSON-RPC mal forméeErreur 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.

Étapes suivantes

Modifier cette page sur GitHub