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é des réponses d'erreur pour créer des intégrations robustes capables de récupérer automatiquement après des défaillances ou de fournir des commentaires utiles aux utilisateurs.

Présentation

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

Structure de la réponse d'erreur

La réponse d'erreur est un objet JSON contenant des champs standards tels que code, message et status. Il inclut également un tableau details. Pour gérer les erreurs de manière programmatique, vous devez rechercher un objet dans details où @type est type.googleapis.com/google.rpc.ErrorInfo.

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

  • domain : regroupement logique de l'erreur, généralement merchantapi.googleapis.com.
  • metadata : mappage 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 ce champ pour gérer les erreurs de manière précise dans votre logique d'application.
    • HELP_CENTER_LINK : fournit des instructions et un contexte 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 qui nécessitent plus de contexte.
    • Autres champs dynamiques : autres clés fournissant du contexte, telles que le nom du champ non valide (FIELD_LOCATION) ou la valeur à l'origine de l'erreur (FIELD_VALUE).

Exemple de réponses d'erreur

Le code JSON suivant illustre la structure d'une erreur de l'API Merchant dans laquelle un nom de ressource est incorrect.

{
  "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 exceptions, il est important de savoir sur quels champs vous pouvez vous appuyer et lesquels sont susceptibles de 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'humain n'est pas stable. Il est destiné uniquement au débogage par les développeurs. N'écrivez pas de code qui analyse le contenu textuel du champ message ou qui s'appuie dessus, 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 indiqué 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 correctement les erreurs.

Utiliser details.metadata.REASON pour la logique

Utilisez toujours le REASON spécifique dans le mappage 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 lu par des humains. Si vous avez besoin d'informations dynamiques (comme le champ qui n'était pas valide), extrayez-les de la carte metadata à l'aide de clés stables telles que FIELD_LOCATION, VARIABLE_NAME.

Mettre en œuvre un intervalle exponentiel entre les tentatives

Pour les erreurs indiquant une indisponibilité temporaire ou une limitation du débit, implémentez une stratégie d'intervalle exponentiel entre les tentatives. Cela signifie qu'il faut attendre un court instant avant de réessayer, et augmenter le temps d'attente à chaque échec ultérieur.

  • quota/request_rate_too_high : cette erreur indique que vous avez dépassé votre quota par minute pour un groupe de quotas spécifique. Réduisez votre taux de demandes.
  • internal_error : ces erreurs sont généralement temporaires. Réessayez avec un intervalle exponentiel entre les tentatives.

Contacter l'assistance Merchant API

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

  1. La réponse d'erreur exacte reçue
  2. Le nom de la méthode d'API
  3. La charge utile de la requête
  4. Horodatages ou période pendant laquelle la méthode a été appelée et les erreurs ont été reçues
Précédent
Track usage metrics
Suivant
Error messages