La version v1beta de l'API Merchant a été abandonnée et arrêtée le 28 février 2026. Pour savoir comment passer à la dernière version stable, consultez Migrer de v1beta vers v1.

Gérer les réponses d'erreur

Ce guide explique comment gérer les erreurs renvoyées par l'API Merchant. Il est essentiel de comprendre la structure et la stabilité de la réponse d'erreur pour créer des intégrations robustes qui peuvent se remettre automatiquement des échecs ou fournir des commentaires pertinents aux utilisateurs.

Présentation

Lorsqu'une requête adressée à l'API Merchant échoue, l'API renvoie un code d'état HTTP standard (4xx ou 5xx) et un corps de réponse JSON contenant des informations détaillées sur l'erreur. L'API Merchant suit la norme AIP-193 pour les informations détaillées sur les erreurs, en fournissant des informations lisibles par machine qui permettent à votre application de gérer des scénarios d'erreur spécifiques par programmation.

Structure de la réponse d'erreur

La réponse d'erreur est un objet JSON qui contient des champs standards tels que code, message, et status. Elle inclut également un tableau details. Pour gérer les erreurs par programmation, recherchez un objet dans details où @type est type.googleapis.com/google.rpc.ErrorInfo.

Cet objet ErrorInfo fournit des données structurées et stables sur l'erreur :

domain : regroupement logique de l'erreur, généralement merchantapi.googleapis.com.
metadata : carte de valeurs dynamiques liées à l'erreur. Par exemple :
- REASON : identifiant spécifique et stable de l'erreur exacte (par exemple, INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS). Ce champ est toujours présent. Utilisez-le pour une gestion des erreurs précise dans la logique de votre application.
- HELP_CENTER_LINK : fournit un contexte et des instructions supplémentaires pour résoudre le problème. Ce champ n'est pas présent pour toutes les erreurs, mais nous prévoyons d'étendre sa couverture au fil du temps pour les erreurs pour lesquelles un contexte supplémentaire peut être nécessaire.
- Autres champs dynamiques : autres clés fournissant un contexte, telles que le nom du champ non valide (FIELD_LOCATION) ou la valeur qui a provoqué l' erreur (FIELD_VALUE).

Exemples de réponses d'erreur

Le JSON suivant illustre la structure d'une erreur de l'API Merchant dans laquelle un nom de ressource a été mal formé.

{
  "error": {
    "code": 400,
    "message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "VARIABLE_NAME": "account",
          "FIELD_LOCATION": "name",
          "FIELD_VALUE": "abcd",
          "REASON": "INVALID_NAME_PART_NOT_NUMBER"
        }
      }
    ]
  }
}

Voici un exemple d'erreur d'authentification :

{
  "error": {
    "code": 401,
    "message": "The caller does not have access to the accounts: [1234567]",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "unauthorized",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_IDS": "[1234567]",
          "REASON": "PERMISSION_DENIED_ACCOUNTS"
        }
      }
    ]
  }
}

Stabilité des champs d'erreur

Lorsque vous écrivez une logique de gestion des erreurs, il est important de savoir sur quels champs vous pouvez vous appuyer et lesquels peuvent changer.

Champs stables :
details.metadata.REASON: identifiant d'erreur spécifique. Vous devez vous appuyer sur ce champ pour la logique de flux de contrôle de votre application.
- Clés details.metadata : les clés de la carte de métadonnées (par exemple, FIELD_LOCATION, ACCOUNT_IDS) sont stables.
- code : le code d'état HTTP de haut niveau (par exemple, 400, 401, 503) est stable.
Champs instables :
- message: le message d'erreur lisible par l'utilisateur n'est pas stable. Il est destiné au débogage par les développeurs uniquement. N'écrivez pas de code qui analyse ou s'appuie sur le contenu textuel du champ message, car il peut être modifié sans préavis pour améliorer la clarté ou ajouter du contexte.
- Valeurs details.metadata : bien que les clés soient stables, les valeurs des clés d'information peuvent changer. Par exemple, si une clé HELP_CENTER_LINK est fournie, l'URL spécifique vers laquelle elle pointe peut être mise à jour vers une page de documentation plus récente sans notification préalable. Toutefois, comme mentionné précédemment, la valeur de details.metadata.REASON est stable.

Bonnes pratiques

Suivez ces bonnes pratiques pour vous assurer que votre intégration gère les erreurs de manière appropriée.

Utiliser `details.metadata.REASON` pour la logique

Utilisez toujours le REASON spécifique dans la carte metadata pour déterminer la cause d'une erreur. Ne vous fiez pas uniquement au code d'état HTTP, car plusieurs erreurs peuvent partager le même code d'état.

Ne pas analyser le message d'erreur

Comme indiqué dans la section sur la stabilité, le champ message est destiné à être utilisé par les humains. Si vous avez besoin d'informations dynamiques (comme le champ non valide), extrayez-les de la carte metadata à l'aide de clés stables telles que FIELD_LOCATION, VARIABLE_NAME.

Mettre en œuvre l'intervalle exponentiel entre les tentatives

Pour les erreurs indiquant une indisponibilité temporaire ou une limitation du débit, mettez en œuvre une stratégie d'intervalle exponentiel entre les tentatives. Cela signifie attendre une courte période avant de réessayer, puis augmenter le temps d'attente à chaque échec suivant.

quota/request_rate_too_high: cette erreur indique que vous avez dépassé votre quota par minute pour un groupe de quotas spécifique. Ralentissez la fréquence de vos requêtes.
internal_error: ces erreurs sont généralement temporaires. Réessayez avec un intervalle exponentiel entre les tentatives. Remarque : Si internal_error persiste après plusieurs tentatives avec intervalle, consultez Contacter l'assistance de l'API Merchant support.

Contacter l'assistance de l'API Merchant

Si vous devez contacter l'assistance de l'API Merchant concernant une erreur spécifique, fournissez les informations suivantes dans votre demande :

Réponse d'erreur exacte reçue
Nom de la méthode API
Charge utile de la requête
Horodatages ou période pendant laquelle la méthode a été appelée et les erreurs ont été reçues