Gestion des erreurs

Le serveur MCP gère les erreurs avec élégance et retourne des messages clairs à votre assistant IA, qui vous les explique ensuite en langage simple. Cette page couvre ce qui peut mal tourner et comment résoudre les problèmes.

Erreurs d'authentification

Erreur	Cause	Correctif
"Missing X-Snipcart-Api-Key header"	Aucune clé API n'a été envoyée avec la requête	Ajoutez l'en-tête X-Snipcart-Api-Key à la configuration de votre serveur MCP
"Invalid API key"	La clé API est incorrecte ou révoquée	Vérifiez que votre clé correspond à celle dans Tableau de bord → Compte → Clés API
"Forbidden"	Votre clé API n'a pas la permission pour cette action	Vérifiez que vous utilisez le bon type de clé (test vs. production)

Limitation de débit

Le serveur MCP applique des limites de débit à deux niveaux pour protéger votre boutique et l'API Snipcart.

Limites de débit globales

Limite	Défaut	Description
Requêtes par minute	100	Fenêtre glissante par clé API
Requêtes simultanées	10	Maximum de requêtes en cours par clé API

Lorsque la limite de débit globale est dépassée, les requêtes retournent un statut 429 avec une valeur retryAfter. La plupart des clients MCP attendront automatiquement et réessaieront.

Lorsque la limite de concurrence est dépassée, les requêtes retournent un statut 503. Cela signifie que trop de requêtes sont traitées simultanément — le client réessaiera après une courte pause.

Limites de débit par outil

Certains outils ont des limites additionnelles pour correspondre aux contraintes propres à Snipcart :

Outil	Limite
create_order_notification	20 appels par 2 minutes
list_discounts	10 appels par minute

Limites de débit de l'API Snipcart

Si l'API Snipcart elle-même retourne un 429 (trop de requêtes), le serveur MCP réessaie automatiquement jusqu'à 2 fois avec un délai exponentiel (jusqu'à 30 secondes d'attente). Vous n'avez rien à faire — cela est géré de manière transparente.

Erreurs courantes

« Ressource non trouvée » (404)

La commande, le client, le produit ou toute autre ressource que vous avez référencé n'existe pas. Vérifiez l'ID ou le jeton. Causes courantes :

• Faute de frappe dans l'identifiant
• La ressource a été supprimée
• Utilisation d'une clé API en mode test pour accéder aux données en mode production (ou vice versa)

« Requête invalide » (400)

Les paramètres envoyés à l'API Snipcart étaient invalides. Cela signifie généralement :

• Un champ requis était manquant (ex. créer un rabais de type coupon sans code)
• Une valeur était hors limites (ex. un rate supérieur à 1)
• Une combinaison invalide de trigger et type sur un rabais

« Conflit » (409)

L'opération ne peut pas être complétée en raison d'un conflit. Par exemple :

• Tentative de suppression d'un rabais qui a été utilisé dans des commandes complétées

« Délai d'expiration de la requête » (408)

L'API Snipcart a mis trop de temps à répondre. Cela peut arriver avec :

• De très grosses boutiques (100k+ commandes)
• Des requêtes complexes avec de larges plages de dates

Si vous auto-hébergez le serveur, augmentez la variable d'environnement SNIPCART_TIMEOUT_MS.

Le remboursement dépasse le total de la commande

Vous verrez cette erreur en tentant de rembourser plus que la valeur totale de la commande. Vérifiez d'abord le total de la commande avec get_order, puis créez le remboursement avec le bon montant.

Format de réponse

Toutes les réponses des outils suivent une structure cohérente.

Élément unique :

{
  "item": { ... }
}

Liste paginée (basée sur le décalage) :

{
  "items": [ ... ],
  "pagination": {
    "total": 100,
    "offset": 0,
    "limit": 20,
    "hasMore": true,
    "nextOffset": 20
  }
}

Liste paginée (jeton de continuation) :

{
  "items": [ ... ],
  "pagination": {
    "hasMore": true,
    "continuationToken": "abc123xyz",
    "total": null
  }
}

Erreur :

{
  "isError": true,
  "error": "Human-readable error message"
}

En pratique, votre assistant IA interprète ces réponses pour vous — vous verrez des résumés en langage clair, pas du JSON brut.

Obtenir de l'aide

Si vous rencontrez un problème qui n'est pas couvert ici :

• Vérifiez que vous utilisez la bonne clé API (mode test vs. production)
• Essayez la même opération dans le tableau de bord Snipcart pour confirmer que la ressource existe
• Pour les instances auto-hébergées, consultez les journaux du serveur pour des informations d'erreur détaillées
• Écrivez-nous à geeks@snipcart.com