Le serveur MCP de la fondation MemberPress AI renvoie des erreurs structurées lorsqu'une requête échoue à l'authentification, dépasse une limite de débit, ne dispose pas de la portée ou de la capacité requise, ou arrive alors que les écritures destructives sont suspendues. Chaque erreur est associée à un code que le client AI ou le développeur peut utiliser pour identifier le problème.
Ce guide répertorie les codes d'erreur générés par le serveur MCP, indique les causes de chacun d'entre eux et explique comment y remédier. Une section consacrée au dépannage traite des problèmes les plus fréquents rencontrés lors de la configuration initiale.
Forme de la réponse d'erreur
Le serveur renvoie des erreurs à deux niveaux, et celles-ci se présentent sous des formes différentes. Il est essentiel d'identifier le champ approprié pour garantir une gestion fiable des erreurs.
Erreurs au niveau de la couche de transport sont rejetées avant le traitement JSON-RPC : les échecs d'authentification et les routes non montées. Elles utilisent le format d'erreur REST de WordPress, avec une chaîne de caractères code et un code d'état HTTP sous data.status:
{
"code" : "auth_required",
"message" : "En-tête d'autorisation requis.",
"data" : { "status" : 401 }
}Erreurs liées aux couches d'outils se produisent après l'authentification, lors de la distribution des outils — la couche de sécurité et les contrôles d'accès. Elles utilisent le format d'erreur JSON-RPC 2.0, dans lequel code est la valeur JSON-RPC générique -32603 et l'identifiant stable et compatible est data.mp_error_code:
{
"code": -32603,
"message": "Les écritures destructives ont été suspendues par un administrateur. Veuillez réessayer plus tard ou contacter le propriétaire du site.",
"data": { "mp_error_code": "WRITES_PAUSED" },
"request_id": "req_011Cc7Bhv5NZnRMgQ9Bg2JBo"
}Match le
data.mp_error_code, et noncode. Chaque erreur de couche d'outils renvoie la même chose-32603; seulementmp_error_codec'est ce qui les distingue. Lerequest_idest unique à chaque appel — utile pour l'assistance, mais jamais pour la mise en correspondance.
Aperçu des catégories d'erreurs
| Catégorie | Identifiant | Couche |
|---|---|---|
| Authentification | auth_required et les erreurs liées aux jetons | Transports (data.status : 401) |
| Route désactivée ou liens permanents | rest_no_route | Transports (data.status : 404) |
| Portée et capacités | SCOPE_INSUFFISANT, CAPACITÉ_INSUFFISANTE | Outil (-32603 + mp_error_code) |
| Couche de sécurité | ÉCRITURE_SUSPENDUE, CONFIRMATION_NON_VALIDE | Outil (-32603 + mp_error_code) |
| Limitation du débit | RATE_LIMITED, public, inscription | Divers — voir « Erreurs de limitation de débit » |
| Validation | erreur_de_validation | Outil (-32603 + mp_error_code) |
| Ressource et état | utilisateur introuvable, nom_d'utilisateur_en_double, déjà_remboursé, le *_introuvable_* famille | Outil (-32603 + mp_error_code) |
| Générique | crédits insuffisants, crédits_indisponibles | Non accessible via les outils MCP — voir ci-dessous |
Erreurs d'authentification
Le serveur vérifie les identifiants à chaque requête. Toutes les routes MCP principales nécessitent un jeton « Bearer » ou une authentification « Basic ».
Une requête avec Pas d'en-tête « Authorization » est rejetée au niveau de la couche de transport :
{
"code" : "auth_required",
"message" : "En-tête d'autorisation requis.",
"data" : { "status" : 401 }
}| Déclencheur | Code | Message |
|---|---|---|
| Aucun identifiant | auth_required | “ En-tête d'autorisation requis. ” |
| En-tête incorrect (autre que « Bearer » ou « Basic ») | auth_required | “ Authentification par nom d'utilisateur et mot de passe ou authentification de base requise. ” |
| Jeton périmé | token_expired | “ Le jeton a expiré. ” |
| Jeton révoqué ou inexistant | auth_required | “ Jeton non valide ou révoqué. ” |
Un jeton expiré renvoie un code distinct. Un jeton révoqué et un jeton qui n'a jamais existé sont délibérément impossibles à distinguer — Les filtres de recherche de jetons excluent les lignes révoquées ; la réponse ne permet donc pas de savoir si un jeton donné a déjà existé.
401 Les réponses sur la voie MCP comportent un WWW-Authenticate en-tête avec la valeur exacte Bearer realm="mcp", resource_metadata="", et l'en-tête est accessible via CORS. Les points de terminaison OAuth l'omettent délibérément.
Résolution : Générez un nouveau jeton à l'aide de l'assistant, ou reconnectez le client pour relancer le processus OAuth. Vérifiez que le jeton n'a pas été révoqué sur le Clients connectés à MCP tabulation.
Erreurs liées au champ d'application et aux capacités
Deux contrôles distincts rejettent un appel d'outil après une authentification réussie. Les deux se traduisent par des erreurs au niveau de la couche d'outils.
Porte de champ. Chaque outil déclare un périmètre requis. Le serveur vérifie sa compatibilité avec les périmètres accordés au jeton avant le traitement. Une connexion en lecture seule appelant memberpress_create_member ne passe pas cette épreuve.
Contrôle des capacités. Chaque outil d'écriture déclare également la capacité WordPress dont il a besoin — par exemple create_users, modifier_utilisateurs, supprimer_utilisateursou options_de_gestion. Le serveur vérifie les capacités du détenteur du jeton avant l'acheminement. Un complet- jeton de portée détenu par un utilisateur sans create_users Je n'arrive toujours pas à créer des membres.
Les portes s'exécutent dans l'ordre — la portée en premier — puis renvoient un résultat codes distincts:
| Portail | mp_error_code | Message |
|---|---|---|
| Champ d'application | SCOPE_INSUFFISANT | L'étendue requise " %s " n'est pas accordée pour ce jeton. |
| Capacité | CAPACITÉ_INSUFFISANTE | Droits insuffisants pour cet outil. L'utilisateur doit disposer du droit " %s ". |
Les deux utilisent l'enveloppe de la couche d'outils — -32603 avec l'identifiant de la stable dans data.mp_error_code:
{
"code": -32603,
"message": "Autorisation insuffisante pour cet outil. L'utilisateur doit disposer de l'autorisation \"create_users\".",
"data": { "mp_error_code": "CAPABILITY_INSUFFICIENT" },
"request_id": "req_..."
}Résolution :
- Défauts de la lunette : La connexion nécessite une autorisation plus étendue. Révocatez-la et créez une nouvelle connexion avec les droits d'écriture requis. Le niveau d'accès maximal doit être défini sur « Accès complet » pour que les nouvelles connexions puissent bénéficier des droits d'écriture ;
- Défaillances fonctionnelles : L'utilisateur WordPress associé au jeton ne dispose pas des droits nécessaires. Connectez-vous en tant qu'utilisateur disposant de ces droits, ou attribuez-les à cet utilisateur.
Erreurs liées à la couche de sécurité
Les mesures de sécurité des agents génèrent leurs propres erreurs au niveau de la couche d'outils. Les Guide des mesures de sécurité pour les agents explique ces mesures ; cette section dresse la liste de leurs refus.
ÉCRITURE_SUSPENDUE
Le « kill switch » suspend toute écriture destructive. Lorsqu'il est actif, le serveur refuse les outils destructifs avec ÉCRITURE_SUSPENDUE — quels que soient les périmètres de la connexion et même lorsque l'appel comporte un jeton de confirmation valide.
Le refus déclenche des tirs contre le Tout d'abord, un appel sans engagement: l'*aperçu* d'un outil destructeur est bloqué, et pas seulement son exécution. Le « kill switch » bloque l'ensemble du chemin d'écriture destructeur ; ainsi, un état en pause ne peut même pas générer de jeton de confirmation. Les outils de lecture continuent de fonctionner.
{
"code": -32603,
"message": "Les écritures destructives ont été suspendues par un administrateur. Veuillez réessayer plus tard ou contacter le propriétaire du site.",
"data": { "mp_error_code": "WRITES_PAUSED" },
"request_id": "req_011Cc7Bhv5NZnRMgQ9Bg2JBo"
}Résolution : un administrateur désactive le « kill switch » depuis le Clients connectés à MCP onglet. Cette pause est une mesure administrative délibérée ; vérifiez pourquoi elle a été activée avant de reprendre les écritures.
CONFIRMATION_NON_VALIDE
Les outils destructifs nécessitent un processus en deux étapes : le premier appel renvoie un aperçu ainsi qu'un jeton de confirmation à usage unique ; le deuxième appel transmet ce jeton dans le confirmer paramètre. Trois causes distinctes aboutissent au même résultat CONFIRMATION_NON_VALIDE erreur — le message ne précise pas ce qui s'est produit :
| Cause | Détails |
|---|---|
| Le jeton a expiré | Le jeton est plus ancien que la fenêtre de 60 secondes |
| Jeton déjà utilisé | Les jetons sont à usage unique |
| Les arguments ont changé | Le jeton est associé à l'outil, aux arguments et à l'utilisateur précis |
{
"code": -32603,
"message": "Le jeton de confirmation n'est pas valide, a expiré ou les arguments ont changé. Appelez l'outil sans `confirm` pour obtenir un nouvel aperçu et un nouveau jeton.",
"data": { "mp_error_code": "CONFIRMATION_INVALID" },
"request_id": "req_011Cc7AK3jF4SA4VLs3qsmBD"
}Résolution : relancer l'outil sans confirmer pour obtenir un nouvel aperçu et un nouveau jeton, puis valider l'opération dans les 60 secondes à l'aide des mêmes arguments. Étant donné qu'un seul code couvre trois causes possibles, un client chargé du dépannage doit relancer l'aperçu plutôt que d'essayer de déterminer quelle protection s'est déclenchée.
Cet échec est intentionnel. Une simple réponse « réussi/échoué » ne permet pas de savoir si un jeton donné a jamais existé, et la procédure de récupération est la même dans tous les cas : relancer l'aperçu.
La réponse est error.data comporte un raison champ à côté du code de niveau supérieur inchangé, avec deux valeurs : expiré_ou_utilisé (le jeton est introuvable — expiré, déjà utilisé ou n'ayant jamais été émis — et reste délibérément masqué) et arguments_modifiés (Le jeton était valide, mais la requête différait de celle affichée dans l'aperçu — relancez l'aperçu et validez le nouveau jeton).
Erreurs liées à la limite de requêtes
Des limites de débit indépendantes protègent le serveur, et la forme de la réponse varie selon le point d'extrémité — le point de terminaison MCP authentifié ne renvoie pas de réponse 429 pas du tout.
| Surface | Limite | Réponse |
|---|---|---|
| Point de terminaison MCP authentifié | 120 requêtes par minute et par jeton (valeur par défaut ; configurable entre 1 et 1 000) — à définir dans l'onglet « Paramètres MCP », où la limitation de débit peut également être désactivée complètement | Erreur JSON-RPC au niveau du protocole HTTP 200 — code -32029, mp_error_code : RATE_LIMITED |
| Point de terminaison MCP public | 60 requêtes par minute et par adresse IP (fixe) | HTTP 429 avec Délai avant nouvelle tentative : 60 |
OAuth /enregistrer | 60 inscriptions par heure et par adresse IP | HTTP 429 avec Délai avant nouvelle tentative : 3600 |
La limite du point de terminaison authentifié apparaît dans l'enveloppe JSON-RPC, et non sous la forme d'une erreur HTTP :
{"jsonrpc":"2.0","id":1,"error":{"code":-32029,"message":"Limite de requêtes dépassée.","data":{"mp_error_code":"RATE_LIMITED"}}}Le point de terminaison public renvoie un corps d'erreur JSON-RPC au format brut contenant son 429:
{"jsonrpc":"2.0","error":{"code":-32000,"message":"Limite de requêtes dépassée. Veuillez réessayer dans une minute."}}Le point de terminaison d'enregistrement renvoie un corps de type OAuth contenant son 429:
{"error":"too_many_requests","error_description":"Trop d'inscriptions de clients à partir de cette adresse IP. Veuillez réessayer dans une heure."}Résolution : Attendez que la fenêtre se réinitialise. Pour le point de terminaison authentifié, effectuez une correspondance sur mp_error_code : RATE_LIMITED — a 200 Le statut ne signifie pas la réussite — et prenez un peu de recul, au moins une minute. Respectez-le. Retry-After à l'adresse indiquée. Pour un volume légitime et constant, utilisez des requêtes groupées ou réduisez la fréquence d'interrogation.
Erreurs de validation
Les échecs de validation sont des erreurs au niveau de la couche d'outils : -32603 avec mp_error_code : validation_error. Les message Cela explique à lui seul le problème : il indique la valeur rejetée et, lorsqu'un vocabulaire s'applique, énumère les valeurs acceptées. Par exemple, la création d'un webhook avec un événement inconnu renvoie :
Événements inconnus : « member-added ». Événements connus : « transaction-completed », ...Les outils d'écriture vérifient la conformité des vocabulaires d'arguments par rapport à leurs schémas, et les valeurs héritées sont rejetées au profit de l'énumération acceptée. Les outils de coupons constituent l'exemple documenté : mode_discount accepte standard ou premier versementet type de réduction accepte pour cent ou dollar. Les valeurs traditionnelles premier, touset plat sont rejetées.
Résolution : corrigez la saisie comme indiqué dans le message — ou consultez la documentation de l'outil schéma d'entrée en outils/liste — puis renvoyez la requête avec les valeurs canoniques. Ne réessayez pas avec les mêmes arguments.
Erreurs liées aux ressources et aux états
Au-delà de la validation, les outils renvoient des codes destinés à l'utilisateur lorsqu'une requête est correctement formée mais ne peut s'appliquer à l'état actuel du site. Ceux-ci respectent la même structure au niveau de l'outil (-32603 + mp_error_code), et leurs messages en expliquent clairement la raison :
| Code | Déclencheur |
|---|---|
utilisateur introuvable | Le membre ou l'utilisateur mentionné n'existe pas. |
*_introuvable_* famille | La ressource mentionnée (transaction, abonnement, webhook, etc.) n'existe pas. |
nom_d'utilisateur_en_double | Création d'un compte dont le nom d'utilisateur est déjà utilisé |
déjà_remboursé | Tentative de remboursement d'une transaction ayant déjà fait l'objet d'un remboursement |
memberpress_not_active | Le plugin MemberPress n'est pas activé |
auto-suppression refusée | supprimer_membre ciblant l'utilisateur qui effectue l'appel — la suppression du compte associé au jeton actuel mettrait fin à la session. La vérification automatique s'exécute en premier, elle a donc la priorité sur la protection administrateur |
admin_suppression_refusée | supprimer_membre ciblant tout utilisateur disposant de la options_de_gestion capacité. Commencez par rétrograder l'utilisateur dans l'interface d'administration de WordPress si la suppression est intentionnelle. |
Résolution : Il s'agit d'états permanents, et non de défaillances temporaires — vérifiez la ressource référencée (ou l'état du site) et corrigez la requête. Une nouvelle tentative sans modification ne peut aboutir.
Des défaillances véritablement internes — stockage_échoué, suppression_échouée, db_error — sont conçues pour rester génériques, afin que les détails relatifs à la couche de stockage ne soient pas divulgués aux clients. Un client qui reçoit l'un de ces messages ne peut que réessayer ultérieurement ou signaler l'échec à l'administrateur du site.
Erreurs de crédit — Non accessibles via MCP
Les appels de prévisualisation passent par la même liste d'autorisation que l'exécution en production et comportent les mêmes mp_error_code — un outil ne doit pas révéler, dans son aperçu, une erreur interne que l'exécution en temps réel masquerait.
La liste blanche des erreurs du serveur comprend deux codes liés au crédit : crédits insuffisants et crédits_indisponibles. Aucun outil MCP ne consomme de crédits IA, et le serveur MCP n'appelle aucune méthode liée aux crédits. Ces codes existent afin que les services en aval puissent transmettre les erreurs liées aux crédits via la réponse JSON-RPC ; aucun chemin d'appel d'un outil MCP ne les génère.
Un client utilisant les outils MCP ne rencontre jamais ces codes. Les soldes créditeurs ont une incidence sur les fonctionnalités de génération basées sur Mastermind (par exemple, Course Copilot), mais pas sur les appels aux outils MCP.
Dépannage des échecs de configuration
Modes de défaillance pouvant survenir lors de la connexion initiale, classés par ordre de fréquence de survenue pour les utilisateurs :
- Le point de terminaison MCP authentifié renvoie
404: Les permaliens sont définis sur « Simple ». L'API REST nécessite des permaliens de type « Nom de l'article » ou plus détaillés ; - Le point de terminaison MCP public renvoie
404(rest_no_route): Le catalogue public est désactivé. Lorsqu'il est désactivé, le route n'est pas monté ; par conséquent, toute requête renvoierest_no_route— l'existence du point de terminaison n'est pas révélée. Activez le catalogue sur le Paramètres MCP tabulation ; - Le point de terminaison renvoie
401(auth_required) dans un navigateur : comportement attendu. Le401confirme que le point de terminaison est actif ; le navigateur ne comporte pas d'en-tête « Authorization » ; - Claude Desktop affiche le connecteur, mais aucun outil : l'autorisation OAuth n'a pas abouti ou la connexion a été révoquée. Ouvrez le connecteur et reconnectez-vous ;
étape=erreur_de_débutlors de la connexion à Claude Desktop : L'enregistrement OAuth est soumis à une limite de 60 tentatives par heure et par adresse IP. Veuillez attendre que le délai soit écoulé, puis réessayez ;- Un client tiers ne peut pas s'enregistrer via OAuth (
uri_de_redirection_non_valide): Le point de terminaison d'enregistrement dynamique n'accepte que les URI de redirection figurant sur la liste blanche (les clients IA connus). Un client dont l'URI de redirection ne figure pas sur la liste blanche est rejeté à/enregistrer; - Un outil attendu manque dans
outils/liste: l'outil appartient à un module complémentaire inactif. Les outils des modules complémentaires ne sont enregistrés que lorsque leur module complémentaire est actif. L'appel d'un outil non enregistré renvoie l'erreur standard JSON-RPC « méthode inconnue » ; - Cases à cocher manquantes dans l'assistant : Le plafond d'accès est défini sur « Lecture seule ». L'assistant masque les étendues d'écriture et affiche un message d'avertissement. Augmentez le plafond sur le Paramètres MCP tabulation ;
- Un outil destructeur affiche un aperçu au lieu de s'exécuter : Comportement attendu. Les outils destructifs nécessitent un processus de confirmation en deux étapes. Transmettez le jeton renvoyé dans le
confirmerparamètre dans un délai de 60 secondes.
Conseils sur la gestion des erreurs
- Match le
data.mp_error_codepour les erreurs liées aux couches d'outils, et surcodeplusdata.statuspour les erreurs au niveau de la couche de transport. Ne jamais effectuer de comparaison sur le simple-32603; auth_required/401: Effectuez une nouvelle authentification. N'essayez pas à nouveau avec les mêmes identifiants ; des échecs répétés déclenchent le verrouillage par attaque par force brute ;SCOPE_INSUFFISANT/CAPACITÉ_INSUFFISANTE: Ne pas réessayer. La connexion nécessite une autorisation plus étendue, ou l'utilisateur associé au jeton doit disposer de la fonctionnalité WordPress manquante — une nouvelle tentative ne peut aboutir ;ÉCRITURE_SUSPENDUE: ne pas réessayer automatiquement. Un administrateur a délibérément suspendu les écritures destructrices ; signaler cet état à l'utilisateur ;erreur_de_validation: Corrigez les données saisies comme indiqué dans le message, puis renvoyez-les. Ne réessayez pas avec les mêmes arguments : les mêmes données saisies entraîneront le même rejet ;CONFIRMATION_NON_VALIDE: relancez le flux à deux appels à partir de l'appel de prévisualisation. Un seul code couvre trois causes possibles ; il est donc préférable de relancer la prévisualisation plutôt que d'essayer de déterminer laquelle s'est déclenchée. Ne mettez jamais en cache les jetons de confirmation ;- Limites de débit : Laisse tomber. Le point de terminaison authentifié signale
RATE_LIMITEDà l'intérieur d'une requête HTTP200; les points de terminaison publics et d'enregistrement renvoient429avecRetry-After. RespectRetry-Aftersi l'envoi a été effectué ; sinon, attendre au moins une minute.
Documentation associée
- Présentation et guide d'installation de MemberPress AI Foundation — installation, conditions préalables et vérifications après l'installation ;
- Connexion des clients IA à MemberPress – Guide de référence pour les développeurs — les méthodes d'authentification et la configuration propre à chaque client ;
- Référence des outils MCP de la certification « AI Foundation » MemberPress — les portées, les fonctionnalités et les schémas propres à chaque outil ;
- Mesures de sécurité relatives aux agents de la plateforme MemberPress AI Foundation — les quatre mesures à l'origine des erreurs liées à la couche de sécurité.
FR 
EN 
ES 
DE 
PT 