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 qui peuvent se rétablir automatiquement en cas d'échec ou fournir des commentaires pertinents aux utilisateurs.

Présentation

Lorsqu'une requête de 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 sur l'erreur. L'API Merchant suit la norme AIP-193 pour les informations sur les erreurs. Elle fournit 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 structurées et stables sur l'erreur :

  • domain : regroupement logique de l'erreur, généralement merchantapi.googleapis.com.
  • metadata : carte des 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 la logique de votre application.
    • HELP_CENTER_LINK : fournit du 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 du contexte, comme 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 code JSON suivant illustre la structure d'une erreur de l'API Merchant où 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 sont susceptibles de changer.

  • Champs stables :

  • details.metadata.REASON : identifiant d'erreur spécifique. Vous devez vous appuyer sur ce champ pour la logique du flux de contrôle de votre application.

    • Clés details.metadata : clés du mappage des métadonnées (par exemple, FIELD_LOCATION, ACCOUNT_IDS) sont stables.
    • code : 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. Elle est destinée 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 changer 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 informatives 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 fluide.

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é à la consommation humaine. 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 et 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 attendre un court laps de temps avant de réessayer, et augmenter le temps d'attente à chaque nouvel échec.

  • 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 demandes.
  • 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 un délai, consultez Contacter l'assistance Merchant API.

Contacter l'assistance Merchant AP

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

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