Pourquoi mon token API Magento expire-t-il toutes les 4 heures ?

C'est le paramètre par défaut pour les tokens Admin User. Créez une Intégration dans Système > Intégrations pour obtenir un token permanent basé sur OAuth.

Comment corriger une erreur 401 Unauthorized dans Magento 2 ?

Basculez des tokens Admin User (4h) vers les Tokens d'Intégration permanents via Système > Extensions > Intégrations. Utilisez le token dans l'en-tête Authorization: Bearer .

Que signifie une erreur 404 sur l'API Magento alors que l'endpoint existe ?

Magento est une architecture multi-boutique. Ajoutez /default/ ou /all/ dans votre URL : /rest/default/V1/products/123 au lieu de /rest/V1/products/123.

février 23, 2026

Corriger les Erreurs API Magento les Plus Courantes : Le Guide de Dépannage du Développeur 2026

Q: Comment déboguer une erreur 500 Internal Server Error dans Magento ?

Connectez-vous en SSH et exécutez : tail -f var/log/exception.log var/log/system.log. Déclenchez à nouveau l'appel API et analysez la stack trace complète dans le terminal.

By ShippyPro Product Team · 7 minute read

Édition 2026 · 5 min de lecture · Par l'équipe Produit ShippyPro

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 / Magento 2 — API REST

Guide de dépannage des intégrations 2026

401 403 404 500

Quand la « Plateforme Puissante » Tombe en Panne

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.

💡 Première intégration ?

Si vous configurez votre connexion pour la première fois, consultez notre guide pas à pas sur comment connecter Magento 2 à ShippyPro.

🗝 Aide-Mémoire Développeur — Les 4 Erreurs Clés

401 Unauthorized : Votre token a expiré. Fix : Passez des tokens Admin (durée de vie 4h) aux Tokens d'Intégration (permanents).
403 Forbidden : Vous êtes connecté, mais vos permissions sont incorrectes. Fix : Vérifiez Système > Rôles Utilisateur > Ressources.
404 Not Found : L'endpoint est correct, mais le contexte est manquant. Fix : Ajoutez /all/ ou /default/ à votre chemin URL (ex. /rest/default/V1/...).
500 Internal Error : Le code a planté. Fix : Ignorez la réponse API. Connectez-vous en SSH et exécutez tail -f var/log/exception.log pour voir l'erreur PHP réelle.

Analyse Approfondie 1 : L'Erreur « 401 Unauthorized » (Le Piège du Token)

401

Unauthorized

Token expiré ou invalide — votre clé d'accès n'est plus reconnue par Magento

→ Tokens d'Intégration

C'est l'obstacle le plus courant pour les nouvelles intégrations. Vous envoyez une requête valide, mais Magento refuse de la traiter.

La Cause Racine : Tokens Admin vs. Tokens d'Intégration

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.

Le Problème : Les tokens Admin sont conçus pour les sessions humaines. Par défaut, ils expirent après 4 heures. Si votre script code en dur un token généré hier, il échouera aujourd'hui.
Le Symptôme : Votre intégration fonctionne parfaitement pendant les tests mais échoue pendant la nuit.

Le Correctif Permanent : Créer une Intégration

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.

Connectez-vous à votre panneau d'administration Magento.

Naviguez vers Système > Extensions > Intégrations.

Cliquez sur Ajouter une nouvelle intégration. Donnez-lui un nom (ex. « Connexion ERP ») et saisissez votre mot de passe.

Étape Cruciale : Cliquez sur l'onglet API à gauche et sélectionnez les ressources exactes dont cette application a besoin (ex. « Ventes », « Catalogue »). N'accordez pas d'accès admin complet sauf si c'est absolument nécessaire.

⚠️ Principe du moindre privilège : limitez toujours les permissions au strict nécessaire pour réduire la surface d'attaque.

Enregistrez et cliquez sur Activer. Magento affichera un Access Token.

Résultat : Utilisez ce token dans l'en-tête de vos requêtes API. Il n'expire jamais.

Authorization: Bearer <votre_token_permanent>

Analyse Approfondie 2 : L'Erreur « 404 Not Found » (Le Fantôme du Routage)

404

Not Found

L'endpoint existe bien — mais le contexte de store est manquant dans l'URL

→ Ajouter /default/ ou /all/

Vous consultez la documentation Swagger d'Adobe Commerce. L'endpoint /V1/products/{sku} existe clairement. Pourtant, quand vous l'appelez, vous obtenez un 404.

La Cause Racine : Le Scope de la Vue de Magasin

Magento 2 est une architecture multi-boutique. Elle supporte plusieurs sites web, magasins et vues (langues) sur une seule installation.

Quand vous appelez la racine /rest/V1/..., Magento essaie de deviner quel magasin vous voulez.
Si votre configuration est complexe, ou si vous essayez d'accéder à des données spécifiques à un magasin (comme une description de produit traduite), l'endpoint racine échouera.

Le Correctif : Routage Explicite

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

💡 Règle Pratique

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.

Analyse Approfondie 3 : L'Erreur « 400 Bad Request » (La Bibliothécaire Stricte)

400

Bad Request

Le serveur a reçu votre requête mais l'a rejetée — les données ne correspondent pas au schéma attendu

→ Valider le JSON via Swagger

Causes Fréquentes dans Magento 2

Erreurs de syntaxe JSON : Une virgule en fin d'objet JSON est valide en JavaScript mais invalide en JSON. Le parser de Magento la rejettera immédiatement.
Champs obligatoires manquants : Si vous essayez de créer une entité Client sans les champs email ou lastname, l'API renvoie un 400.
Type d'attribut incorrect : Envoyer une chaîne "10" à un champ défini comme integer ou float peut provoquer des erreurs de validation en mode strict.

La Solution : Utilisez Votre Swagger Local

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.

🌐 Accéder à votre Swagger local

https://votre-domaine-magento.com/swagger

Cette 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.

Analyse Approfondie 4 : L'Erreur « 500 Internal Server Error » (La Boîte Noire)

500

Internal Server Error

PHP a planté — l'API ne vous donnera aucune information utile. Il faut aller dans les logs serveur.

→ SSH + exception.log

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"}.

La Cause Racine

Une erreur 500 signifie que PHP a planté. Cela peut être dû à :

Épuisement de la mémoire : Vous avez essayé de charger 5 000 produits en un seul appel, dépassant la limite mémoire PHP.
Conflit de plugin tiers : Un « Observer » ou « Plugin » déclenché par votre action de sauvegarde API contient un bug.
Verrou de base de données : Un autre processus verrouille la ligne que vous essayez de mettre à jour.

Le Correctif : La Commande « Tail »

Vous ne pouvez pas déboguer une erreur 500 depuis un client API (Postman/Insomnia). Vous devez aller sur le serveur.

Connectez-vous en SSH à votre serveur Magento.

Naviguez vers le répertoire racine de votre installation Magento.

Exécutez cette commande pour surveiller les logs en temps réel :

tail -f var/log/exception.log var/log/system.log

Déclenchez à nouveau l'appel API depuis votre client.

Analysez : Le terminal affichera la stack trace complète. Cherchez des lignes comme :

Uncaught Error: Call to a member function...
SQLSTATE[HY000]: General error...

Cela vous indique exactement quel fichier et quelle ligne ont provoqué le crash.

⚠ Pro Tip : L'API Bulk pour les Performances

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.

Matrice de Dépannage Complète

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.

Transformer la Boîte Noire en Maison de Verre

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.

Explorez Nos Ressources pour Aller Plus Loin

Maîtrisez vos intégrations Magento et automatisez vos expéditions depuis la France :

Produit

Automatisation IA

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 →

Produit

Shipping Platform

Automatisez la préparation des commandes Magento et la gestion de la livraison pour 190+ transporteurs depuis une interface unique.

Découvrir →

API

Documentation API ShippyPro

Intégrez directement ShippyPro à votre stack Magento via notre API REST documentée et nos webhooks.

Explorer →

Guide

Connexion Magento 2 → ShippyPro

Guide pas à pas pour connecter votre boutique Adobe Commerce à ShippyPro et synchroniser vos commandes automatiquement.

Lire le guide →

Support

Résoudre les Erreurs Magento

Liste complète des codes d'erreur Magento avec solutions détaillées pour chaque cas d'intégration ShippyPro.

Consulter →

Hub

Toutes nos Ressources

Analyses sectorielles, guides techniques et outils gratuits pour optimiser votre stack logistique.

Explorer →

FAQ — Questions Fréquentes sur l'API Magento

Pourquoi mon token API expire-t-il toutes les 4 heures ?

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.

Comment filtrer les commandes par date via l'API ?

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]=gt

Ici, gt signifie « supérieur à » (greater than).

Puis-je utiliser l'API pour réindexer les données ?

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 »).

Comment déboguer une erreur 403 Forbidden sur mon intégration ?

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.

Automatisez vos expéditions Magento sans les maux de tête

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 →

ShippyPro Product Team

L'équipe produit de ShippyPro se consacre à la création de solutions innovantes qui permettent aux entreprises de simplifier leurs opérations d'expédition. En combinant la recherche sur les clients avec une technologie de pointe, nous concevons des fonctionnalités qui améliorent l'efficacité, réduisent les efforts et augmentent la flexibilité logistique.