Quotas

Ce document liste les quotas qui s'appliquent à l'API Merchant.

L'API Merchant utilise des quotas pour garantir un environnement stable et équitable pour tous les utilisateurs. Les quotas empêchent un utilisateur d'API de surcharger le système, ce qui garantit des performances élevées. Il est essentiel de comprendre ces quotas pour gérer vos données produit et développer votre activité sur Google.

Concepts généraux

Les quotas de Merchant API sont gérés via des groupes de quotas.

Les méthodes d'API sont mappées à des groupes de quotas. La structure de ce mappage peut varier :

  • Une seule méthode par groupe : certains groupes de quotas s'appliquent à une seule méthode d'API. Par exemple, la méthode de listage des sources de données accounts.dataSources.list dispose de son propre groupe de quotas dédié.
  • Plusieurs méthodes par groupe (regroupement) : souvent, les méthodes associées sont regroupées dans un seul groupe de quotas. Toutes les méthodes de ce groupe partagent les mêmes limites quotidiennes et par minute. Voici quelques exemples courants :
    • Regroupement de toutes les opérations de lecture pour les méthodes et ressources associées, telles que merchant-accounts-read-methods.
    • Regroupement de toutes les opérations d'écriture pour les méthodes et ressources associées, telles que merchant-accounts-write-methods.

Chaque appel de méthode est comptabilisé une fois, quel que soit son type. Une requête list de 250 éléments n'est comptabilisée qu'une seule fois, et non comme 250 requêtes get.

Le traitement par lot HTTP intégré n'a aucune incidence sur le quota. Chaque requête d'un lot de requêtes est comptabilisée comme une requête dans le quota. Par exemple, une requête par lot contenant 500 requêtes insert est facturée comme 500 requêtes de méthode insert individuelles.

Exception pour le traitement par lot de régions dédiées : les méthodes de traitement par lot de régions spécialisées (batchCreate, batchUpdate, batchDelete) sont comptabilisées comme un seul appel d'API par rapport au groupe de quotas merchant_regions, quel que soit le nombre d'opérations de région contenues dans la charge utile.

Pour gérer efficacement votre intégration, vous devez examiner le groupe de quotas spécifique associé à chaque méthode d'API que vous prévoyez d'utiliser. Vous trouverez ces informations dans la méthode de liste des quotas. Pour en savoir plus, consultez Surveillance et visibilité.

Règles relatives à la mise à jour

L'API Merchant applique les règles suivantes en termes de mises à jour :

  • Par défaut, vous pouvez mettre à jour vos produits jusqu'à deux fois par jour. Vous devez répartir les appels de manière uniforme tout au long de la journée pour respecter le quota par minute.
  • Par défaut, vous ne pouvez mettre à jour vos sous-comptes que deux fois par jour. Votre quota quotidien de mise à jour des sous-comptes est une limite globale basée sur le nombre total de sous-comptes autorisés.
  • Par défaut, vous ne pouvez appeler les méthodes de source de données pour vos sous-comptes, telles que list ou create, que deux fois par sous-compte et par jour.

Les quotas de débit

Chaque groupe de quotas comporte deux types de limites (et d'utilisation quotidienne) :

  • Limite quotidienne (quotaLimit) : nombre maximal de requêtes autorisées par jour. Les limites de quota quotidiennes sont réinitialisées à 12h00 UTC.
  • Limite par minute (quotaMinuteLimit) : nombre maximal de requêtes autorisées par minute, qui contrôle le taux de requêtes. Les limites de quota par minute utilisent une fenêtre glissante, où la période d'application commence au moment où le premier appel d'API pour cette méthode et cette ressource est effectué. Par exemple, si vous effectuez un appel à 10:01:30, la fenêtre de quota par minute pour cette méthode s'exécute jusqu'à 10:02:30.
  • Utilisation quotidienne (quotaUsage) : nombre de requêtes déjà effectuées et comptabilisées dans la limite quotidienne pour le jour en cours. Si le champ est manquant, cela signifie qu'aucun quota n'a encore été consommé pour ce groupe.

Vous trouverez les trois champs décrits précédemment (quotaLimit, quotaMinuteLimit et quotaUsage) dans la réponse de la méthode quotas.list.

Les limites quotidiennes et par minute spécifiques varient considérablement d'un groupe de quotas à l'autre. Les opérations dont le volume attendu est plus élevé ou dont le coût système est plus faible, comme la lecture des données produit, ont généralement des limites plus élevées. À l'inverse, les opérations plus intensives ou sensibles, telles que les modifications de compte, peuvent avoir des limites inférieures.

Attribution et hiérarchie des quotas

Cette section explique pour qui l'API Merchant suit et applique l'utilisation des quotas :

En général, le quota est facturé en fonction de l'utilisateur qui effectue la requête API.

  • Comptes autonomes : pour les comptes autonomes authentifiant un appel d'API, cette requête est comptabilisée dans le quota de ce compte.
    • Exemple : Un marchand Shoe Store A (ID de compte : 12345) s'authentifie à l'aide de son propre compte de service pour appeler products.insert en ciblant son propre compte (accounts/12345). Le quota est consommé à partir du pool de quotas de Shoe Store A.
  • Comptes avancés : l'authentification en tant que compte avancé consomme le quota du pool du compte avancé, même lorsque vous ciblez un sous-compte.
    • Exemple : Un compte de gestion de commerce d'agence (ID de compte avancé : 12345) gère un sous-compte Magasin de vêtements B (ID de compte : 11111). L'agence s'authentifie à l'aide de ses propres identifiants et appelle products.insert en ciblant le magasin de vêtements B (accounts/11111). Le quota est consommé à partir du pool de l'agence parente (ID de compte avancé : 12345), et non de celui du sous-compte.
  • Sous-comptes : lorsque les appels d'API sont authentifiés à l'aide des identifiants d'un sous-compte, le quota est imputé au pool individuel de ce sous-compte. Il fonctionne de la même manière qu'un compte autonome, même s'il est géré par un compte avancé parent.
    • Exemple : en utilisant la même configuration que précédemment, si le magasin de vêtements B (ID de compte : 11111) s'authentifie à l'aide d'identifiants configurés spécifiquement pour son sous-compte afin d'appeler products.insert en ciblant son propre compte (accounts/11111), le quota est consommé à partir du pool de quotas individuel du magasin de vêtements B, sans que le pool de l'agence parente ne soit affecté.

Exceptions aux règles générales

Il existe quelques exceptions spécifiques qui s'appliquent aux règles générales d'allocation de quota :

  • Accounts.list : le quota de cette méthode est imputé à l'utilisateur authentifié ou au compte de service qui effectue l'appel, et non à l'ID du compte Merchant Center. Son utilisation du quota ne sera pas visible sur la page standard de diagnostic de l'API Merchant Center. Si vous disposez d'un compte avancé, nous vous recommandons d'utiliser la méthode accounts.listSubaccounts, qui est comptabilisée dans votre quota de comptes avancés.
  • Méthodes de résolution des problèmes : ces méthodes sont toujours comptabilisées dans le quota du compte dont les problèmes sont demandés, même si un autre compte authentifie la requête.

Hiérarchie d'allocation

  • Services de comparateur de prix (CSS) : les CSS sont des sites Web qui regroupent des offres de produits et redirigent les utilisateurs vers les sites Web des marchands pour qu'ils effectuent leurs achats. Lorsque vous effectuez des appels d'API, les quotas sont appliqués au groupe CSS, au domaine CSS, au compte ou au sous-compte spécifique auprès duquel vous vous authentifiez.

    Exemples :

    • Un groupe CSS nommé Europe Shopping Group (ID de compte : 10001) souhaite lister ses domaines CSS associés. En s'authentifiant avec ses propres identifiants pour effectuer cet appel d'API, le quota est consommé directement à partir du pool de quotas du groupe Shopping Europe.
    • Un domaine CSS TopDeals CSS (ID de compte : 20002) s'authentifie pour appeler une méthode ciblant l'un de ses comptes marchands associés (accounts/30003) afin d'attribuer un libellé. Le quota est consommé à partir du pool de quotas de TopDeals CSS, et non de celui du compte marchand.

  • Places de marché : les places de marché sont des plates-formes en ligne qui hébergent plusieurs marchands individuels. Ils fonctionnent comme des comptes avancés spéciaux qui vous permettent de créer des sous-comptes individuels pour chacun de vos vendeurs.

Le schéma suivant montre la hiérarchie des groupes CSS, des CSS, des places de marché, des comptes avancés, des comptes individuels et des sous-comptes.

Un groupe CSS est le niveau d'authentification global, avec la possibilité d'avoir des CSS individuels, des comptes dans ces CSS et des sous-comptes au niveau le plus individuel.

Ajustement automatique des quotas

Merchant API dispose d'un système de gestion automatique des quotas pour des services spécifiques, qui ajuste les limites de quota pour les marchands en croissance en fonction de votre utilisation, de votre offre et de la taille de votre compte. L'API Merchant recalcule ces quotas tous les jours.

Les groupes de quotas inclus dans les ajustements automatiques des quotas sont les suivants :

Services de produits

  • Tous les groupes de quotas de méthodes liés aux ressources products et productInputs.
  • Le quota d'appels quotidien est généralement défini sur deux fois le nombre de quotas d'offres dont dispose le marchand. Cela suppose qu'un marchand peut avoir besoin de mettre à jour chacun de ses produits jusqu'à deux fois par jour.
  • Les produits individuels peuvent être mis à jour plus de deux fois, mais le nombre total d'appels d'API quotidiens ne peut pas dépasser le quota d'appels quotidien global.

Services de comptabilité

  • Tous les groupes de quotas de méthodes liés aux différentes ressources granulaires liées au compte dans l'API Merchant.
  • Le quota d'appels quotidien est défini sur le nombre maximal de sous-comptes autorisé pour ce compte. Cela permet d'effectuer jusqu'à deux appels de lecture par sous-compte et par jour.

Services de sources de données

  • Tous les groupes de quotas de méthodes liés aux ressources associées à la source de données dans l'API Merchant, comme list ou create, qu'un compte avancé exécute sur ses sous-comptes.
  • Le quota d'appels quotidien est généralement défini sur deux fois le nombre de sous-comptes du compte avancé. Cela suppose qu'un marchand peut mettre à jour les sources de données de chacun de ses sous-comptes jusqu'à deux fois par jour.

Seuls les services décrits précédemment bénéficient d'ajustements automatiques des quotas. D'autres services ont un quota par défaut, et toute augmentation doit être demandée manuellement. Pour en savoir plus, consultez la section Processus d'augmentation de quota.

Que se passe-t-il lorsque les quotas sont dépassés ?

Une fois qu'un quota a été dépassé, des erreurs s'affichent dans les réponses de l'API et sur la page de diagnostic de votre compte Merchant Center :

  • Par minute : quota/request_rate_too_high
{
    "error": {
        "code": 429,
        "message": "Quota per minute exceeded. Please distribute your requests over a longer time period. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
        "status": "RESOURCE_EXHAUSTED",
        "details": [
            {
                "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                "reason": "quotaExceeded",
                "domain": "merchantapi.googleapis.com",
                "metadata": {
                    "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
                    "REASON": "QUOTA_REQUEST_RATE_TOO_HIGH"
                }
            }
        ]
    }
}
  • Par jour : quota/daily_limit_exceeded
{
    "error": {
        "code": 429,
        "message": "Daily request quota exceeded. Please reduce number of requests. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
        "status": "RESOURCE_EXHAUSTED",
        "details": [
            {
                "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                "reason": "quotaExceeded",
                "domain": "merchantapi.googleapis.com",
                "metadata": {
                    "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
                    "REASON": "QUOTA_TOO_MANY_REQUESTS"
                }
            }
        ]
    }
}

Les erreurs suivantes sont des limites de Merchant Center et ne sont pas liées aux quotas de l'API Merchant. Vous pouvez essayer de demander un quota supplémentaire d'articles, de flux ou de sous-comptes :

  • too_many_items : quota Merchant Center dépassé
  • too_many_subaccounts : Nombre maximal de sous-comptes atteint

Surveillance et visibilité

Pour vérifier les quotas d'appels et l'utilisation actuels d'un compte, appelez quotas.list avec le nom du compte.

POST https://merchantapi.googleapis.com/quota/v1/accounts/{ACCOUNT_ID}/quotas
Content-Type: application/json
Authorization: Bearer {ACCESS_TOKEN}

Remplacez les éléments suivants :

  • ACCOUNT_ID : votre ID Merchant Center
  • ACCESS_TOKEN : jeton d'autorisation permettant d'effectuer l'appel d'API.

Si la requête aboutit, l'API renvoie une liste de ressources quotaGroups contenant la ressource name du groupe de quotas, les différents quotas et les méthodes auxquelles le quota du groupe s'applique.

{
    "quotaGroups": [
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-quota-listquotagroups",
            "quotaUsage": "2",
            "quotaLimit": "1000",
            "methodDetails": [
                {
                    "method": "quotaservice.listquotagroups",
                    "version": "v1",
                    "subapi": "quota",
                    "path": "quota/v1/quotaservice.listquotagroups"
                }
            ],
            "quotaMinuteLimit": "10"
        },
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-commission-group-list",
            "quotaLimit": "10000",
            "methodDetails": [
                {
                    "method": "commissiongroupservice.listcommissiongroups",
                    "version": "v1",
                    "subapi": "youtube",
                    "path": "youtube/v1/commissiongroupservice.listcommissiongroups"
                }
            ],
            "quotaMinuteLimit": "60"
        },
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-merchantreviews-list",
            "quotaLimit": "20000000",
            "methodDetails": [
                {
                    "method": "merchantreviewsservice.listmerchantreviews",
                    "version": "v1",
                    "subapi": "reviews",
                    "path": "reviews/v1/merchantreviewsservice.listmerchantreviews"
                }
            ],
            "quotaMinuteLimit": "60000"
        }
    ]
}

Processus d'augmentation de quota

Pour demander un quota supplémentaire, ouvrez le formulaire de contact de l'assistance, sélectionnez "Demande d'augmentation de quota" dans le champ obligatoire "Quel est le problème/la question ?", puis remplissez tous les champs obligatoires, y compris votre ID Merchant Center, les méthodes cibles et la justification commerciale.

  • Pour les ressources avec des quotas automatiques (products, accounts et datasources pour les comptes avancés) : vous ne pouvez demander qu'une augmentation temporaire pour des scénarios spécifiques, comme le lancement sur un nouveau marché ou pendant les périodes d'achats à fort trafic. Nous n'acceptons pas les augmentations de quota permanentes pour ces types de ressources.
  • Pour toutes les autres ressources sans quotas automatiques : demandez des augmentations de quota si nécessaire.

Nous vous recommandons de vérifier régulièrement vos quotas pour vous assurer que vous disposez d'un quota suffisant pour votre implémentation et pour voir comment votre quota est ajusté automatiquement. Utilisez la méthode quotas.list pour afficher votre limite de quota quotidienne actuelle, votre limite par minute et votre utilisation quotidienne actuelle pour chaque groupe de méthodes d'API.

Bonnes pratiques

En appliquant ces bonnes pratiques, vous vous assurez que votre intégration se déroule sans problème, vous évitez les erreurs de quota inattendues et vous utilisez efficacement les ressources Merchant Center.

Optimiser la distribution des requêtes

  • Répartissez les requêtes de manière uniforme : évitez d'envoyer des pics de requêtes. Répartissez vos appels d'API quotidiens de manière uniforme tout au long de la journée pour ne pas dépasser les limites de quota par minute (quotaMinuteLimit).
  • Limitation proactive : implémentez une limitation du débit côté client (limitation) dans votre application. Ne comptez pas uniquement sur les serveurs de Google pour rejeter le trafic excédentaire. Contrôlez votre taux de demandes à la source.

Gestion optimale des exceptions

  • Gérer les erreurs HTTP 429 : votre application doit être prête à gérer les erreurs 429 "Too Many Requests" (quota/request_rate_too_high).
  • Intervalle exponentiel entre les tentatives avec gigue : lorsque vous relancez des requêtes ayant échoué (en particulier après une erreur 429), utilisez un intervalle exponentiel entre les tentatives (temps d'attente croissants) et ajoutez une "gigue" (délai aléatoire). La gigue empêche les "tempêtes de nouvelles tentatives", où plusieurs instances clientes effectuent une nouvelle tentative exactement au même moment, surchargeant à nouveau le serveur.
  • Respecter les indications de nouvelle tentative : si la réponse de l'API contient des détails ou des en-têtes de nouvelle tentative, utilisez-les pour déterminer quand reprendre les appels.

Réduire les appels redondants

  • Éviter les appels obsolètes (404 NOT_FOUND) : évitez de demander ou de supprimer des ressources qui n'existent plus. Même les appels ayant échoué consomment du quota d'API. Surveillez les erreurs NOT_FOUND dans le diagnostic de l'API Merchant Center pour détecter un suivi d'état obsolète ou une interrogation inutile.
  • Vérifier avant de mettre à jour : avant d'envoyer une requête de mise à jour, vérifiez si les données ont réellement changé. Évitez d'envoyer des mises à jour qui écrivent les mêmes valeurs.
  • Utiliser la mise en cache : mettez en cache les réponses de lecture (par exemple, les informations détaillées sur le produit, les paramètres) localement, le cas échéant, pour éviter les appels get ou list répétitifs pour les données inchangées.
  • Comptes avancés et sous-comptes : si vous disposez d'un compte avancé, authentifiez-vous au niveau du compte avancé si vous souhaitez que les appels soient comptabilisés dans le pool partagé des comptes avancés.
  • Utilisez listSubaccounts : pour les comptes avancés, utilisez accounts.listSubaccounts au lieu de accounts.list. Le quota accounts.list est facturé à l'utilisateur appelant (et non à l'ID MC) et n'est pas visible dans les diagnostics standards. listSubaccounts est décompté de votre quota de MC.
Précédent
Overview
Suivant
Merchant Center limits