API en panne sur Adobe Commerce ? Des erreurs « 401 Unauthorized » aux mystérieux « 500 Internal Server Error », voici le guide définitif pour déboguer vos intégrations REST Magento 2.
Adobe Commerce (anciennement Magento 2) est largement reconnu comme la plateforme e-commerce la plus flexible du marché. Mais cette flexibilité a un prix : la rigueur.
Pour les développeurs qui construisent des intégrations — qu'il s'agisse de connecter un ERP, un PIM ou une plateforme d'automatisation des expéditions comme ShippyPro — l'API REST Magento peut être impitoyable. Une virgule manquante dans un payload JSON ou une liste de contrôle d'accès (ACL) légèrement mal configurée peut bloquer toute votre synchronisation de données.
Contrairement à d'autres plateformes qui renvoient des messages d'erreur utiles comme « Adresse e-mail invalide », Magento retourne souvent des codes de statut génériques qui vous laissent dans le brouillard.
Dans ce guide complet, nous allons aller au-delà des définitions basiques. Nous allons déconstruire la logique derrière les erreurs API les plus fréquentes de Magento, explorer les logs serveur à surveiller, et fournir des correctifs architecturaux permanents pour stabiliser vos intégrations.
Si vous configurez votre connexion pour la première fois, consultez notre guide pas à pas sur comment connecter Magento 2 à ShippyPro.
/all/ ou /default/ à votre chemin URL (ex. /rest/default/V1/...).tail -f var/log/exception.log pour voir l'erreur PHP réelle.C'est l'obstacle le plus courant pour les nouvelles intégrations. Vous envoyez une requête valide, mais Magento refuse de la traiter.
Magento propose plusieurs méthodes d'authentification. Une erreur fréquente consiste à utiliser l'endpoint Token Admin (POST /V1/integration/admin/token) pour des applications externes.
Si vous suspectez que vos identifiants sont invalides, vérifiez-les avec notre guide de résolution des problèmes de connexion Magento.
N'augmentez pas la durée de vie du token admin (c'est un risque de sécurité). Générez plutôt un Bearer Token permanent.
Authorization: Bearer <votre_token_permanent>Vous consultez la documentation Swagger d'Adobe Commerce. L'endpoint /V1/products/{sku} existe clairement. Pourtant, quand vous l'appelez, vous obtenez un 404.
Magento 2 est une architecture multi-boutique. Elle supporte plusieurs sites web, magasins et vues (langues) sur une seule installation.
/rest/V1/..., Magento essaie de deviner quel magasin vous voulez.Définissez toujours le scope dans votre structure d'URL.
| Type | URL | Utilisation |
|---|---|---|
| ❌ Requête ambiguë | GET /rest/V1/products/123 |
Magento « devine » — peut échouer |
| ✅ Scope global | GET /rest/all/V1/products/123 |
Valeurs système (prix devise de base) |
| ✅ Scope par défaut | GET /rest/default/V1/products/123 |
Valeurs vitrine (descriptions traduites) |
| ✅ Scope spécifique | GET /rest/fr/V1/products/123 |
Vue de magasin française uniquement |
Utilisez /all/ pour les valeurs système (prix en devise de base). Utilisez /default/ ou un code spécifique comme /fr/ pour les valeurs spécifiques à la vitrine.
email ou lastname, l'API renvoie un 400."10" à un champ défini comme integer ou float peut provoquer des erreurs de validation en mode strict.Ne vous fiez pas à la documentation générique en ligne. Magento génère une documentation basée sur votre instance spécifique, incluant vos attributs personnalisés.
https://votre-domaine-magento.com/swaggerCette page interactive montre le schéma JSON exact que votre magasin spécifique requiert. Testez d'abord votre payload là-dedans. Si ça fonctionne dans Swagger, ça fonctionnera dans votre code.
C'est l'erreur la plus redoutée car la réponse API ne vous donne aucune information. Elle dit généralement juste {"message": "Internal Server Error"}.
Une erreur 500 signifie que PHP a planté. Cela peut être dû à :
Vous ne pouvez pas déboguer une erreur 500 depuis un client API (Postman/Insomnia). Vous devez aller sur le serveur.
tail -f var/log/exception.log var/log/system.logUncaught Error: Call to a member function...
SQLSTATE[HY000]: General error...Si vous obtenez fréquemment des 504 Gateway Timeouts ou des 500 Errors lors de mises à jour de catalogues volumineux, arrêtez d'utiliser les endpoints REST standards. Magento 2 offre une API Async/Bulk (/async/bulk/V1/...). Au lieu de traiter les données immédiatement, Magento accepte la requête, la place dans une file RabbitMQ, et retourne instantanément un 202 Accepted. Les workers en arrière-plan traitent les données à leur propre rythme, évitant les timeouts et les crashes mémoire.
| Code HTTP | Signification Magento | Action Immédiate |
|---|---|---|
| 401 | Token expiré ou invalide | Basculez vers les Tokens d'Intégration (Système > Intégrations). |
| 403 | Permission ACL refusée | Vérifiez les Rôles Utilisateur. Ce token a-t-il accès à cette ressource ? |
| 404 | Scope de magasin manquant | Ajoutez /all/ ou /default/ au chemin URL. |
| 405 | Méthode HTTP incorrecte | Vous avez utilisé POST sur un endpoint qui n'accepte que PUT. |
| 500 | Crash PHP | Consultez var/log/exception.log via SSH. |
| 503 | Mode Maintenance | Le site est en maintenance. Exécutez bin/magento maintenance:disable. |
Pour une liste plus détaillée des codes d'erreur et le dépannage spécifique à ShippyPro, consultez notre guide de résolution des erreurs Magento.
Déboguer Magento demande de la patience et les bons outils. En passant des tokens admin aux intégrations et en surveillant vos logs d'exception, vous pouvez transformer un système opaque en infrastructure fiable et transparente.
Maîtrisez vos intégrations Magento et automatisez vos expéditions depuis la France :
Connectez Magento à ShippyPro et automatisez la génération d'étiquettes, la sélection de transporteur et le suivi — sans code supplémentaire.
Découvrir →Automatisez la préparation des commandes Magento et la gestion de la livraison pour 190+ transporteurs depuis une interface unique.
Découvrir →Intégrez directement ShippyPro à votre stack Magento via notre API REST documentée et nos webhooks.
Explorer →Guide pas à pas pour connecter votre boutique Adobe Commerce à ShippyPro et synchroniser vos commandes automatiquement.
Lire le guide →Liste complète des codes d'erreur Magento avec solutions détaillées pour chaque cas d'intégration ShippyPro.
Consulter →Analyses sectorielles, guides techniques et outils gratuits pour optimiser votre stack logistique.
Explorer →C'est le paramètre de sécurité par défaut pour les tokens Admin User. Magento suppose qu'un humain est connecté. Pour éviter ce problème dans les scripts automatisés, créez une Intégration dans le menu système. Les intégrations utilisent la logique OAuth et fournissent des tokens qui n'expirent pas sauf révocation manuelle.
Magento utilise searchCriteria. Vous ne pouvez pas simplement ajouter ?date=today. Vous devez construire une chaîne de paramètres comme :
searchCriteria[filter_groups][0][filters][0][field]=created_at
&searchCriteria[filter_groups][0][filters][0][value]=2025-01-01
&searchCriteria[filter_groups][0][filters][0][condition_type]=gtIci, gt signifie « supérieur à » (greater than).
Techniquement oui, mais c'est dangereux. Déclencher une réindexation complète via API pendant les heures de fort trafic peut verrouiller les tables de base de données et ralentir le checkout pour vos clients. La meilleure pratique est de laisser les cron jobs internes de Magento gérer l'indexation (« Mise à jour selon planning »).
Une erreur 403 signifie que votre token est valide mais que ses permissions sont insuffisantes. Allez dans Système > Rôles Utilisateur, trouvez le rôle associé à votre intégration, et vérifiez que les ressources dont vous avez besoin (ex. Sales > Orders) sont bien cochées. Si vous venez d'ajouter un nouveau module Magento, ses ressources ACL n'apparaissent dans l'interface qu'après un bin/magento setup:upgrade.
Connectez votre boutique Adobe Commerce à ShippyPro et laissez notre intégration pré-construite gérer le travail complexe — synchronisation des commandes, génération d'étiquettes et sélection automatique du transporteur.
Créez votre compte gratuit et synchronisez vos commandes Magento →