Plafonds

Un plafond correspond au nombre d’appels d’API qu’une application ou un·e utilisateur·ice peut effectuer sur une période donnée. Si ce plafond ou les limites en termes de CPU ou de temps total sont dépassé·es, l’application ou l’utilisateur·ice pourrait être régulé·e. Dans ce cas, les demandes d’API envoyées par cette application ou cet·te utilisateur·ice échoueront.

Toutes les demandes d’API font l’objet de plafonds. Les demandes de l’API Graph et de l’API Basic Display pour Instagram sont soumises aux Plafonds de plateforme, tandis que les demandes de l’API Marketing et de l’API Graph pour Instagram sont soumises aux Plafonds Business Use Case (BUC).

Les demandes de l’API Pages sont soumises aux plafonds de plateforme ou BUC, selon le token utilisé dans la demande. Les demandes effectuées avec le token d’application ou le token d’accès utilisateur·ice sont soumises aux plafonds de plateforme, tandis que les demandes effectuées avec le token utilisateur·ice système ou les tokens d’accès de Page sont soumises aux plafonds Business Use Case.

Les statistiques d’utilisation des plafonds en temps réel sont décrites dans des en-têtes qui sont inclus avec la plupart des réponses d’API une fois que les appels effectués vers un point de terminaison sont en nombre suffisant. Les statistiques d’utilisation du plafond de plateforme sont également affichées dans l’Espace App. Une fois qu’un plafond est atteint, toute demande ultérieure faite par votre application échoue et l’API renvoie un code d’erreur jusqu’à ce qu’un délai suffisant se soit écoulé pour que le volume d’appels soit inférieur au plafond.

S’il est possible d’appliquer aussi bien les plafonds de plateforme que BUC à une demande, les plafonds BUC s’appliquent.

Plafonds de plateforme

Le suivi des plafonds de plateforme s’effectue au niveau de l’application ou de l’utilisateur·ice, selon le type de token utilisé dans la demande.

Applications

Les demandes de l’API Graph effectuées avec un token d’accès d’application sont comptabilisées dans le plafond de cette application. Le volume d’appels d’une application correspond au nombre d’appels qu’elle peut effectuer durant une période donnée (une heure), calculé comme suit :

Le nombre d’utilisateur·ices est basé sur le nombre de personnes uniques qui utilisent quotidiennement une application. En cas de périodes d’utilisation quotidienne particulièrement ténues, par exemple lorsque votre application a une activité forte le week-end mais faible dans la semaine, c’est le nombre d’utilisateur·ices actif·ives hebdomadaires, voire mensuels, qui servira à calculer le nombre d’utilisateur·ices pour votre application. Les applications à fort taux d’interactions quotidiennes disposeront de plafonds plus élevés que les applications à faible taux d’interactions quotidiennes, indépendamment du nombre réel d’installations d’application.

Notez qu’il ne s’agit pas d’un plafond par utilisateur·ice mais d’un plafond pour les appels effectués par votre application. N’importe quel·le utilisateur·ice peut passer plus de 200 appels par heure à l’aide de votre application, tant que le total d’appels à partir de celle-ci ne dépasse pas le maximum défini pour l’application. Par exemple, si votre application a 100 utilisateur·ices, cela signifie qu’elle peut passer 20 000 appels par heure. Cependant, vos dix utilisateur·ices qui interagissent le plus pourraient passer 19 000 de ces appels.

Utilisateur·ices

Les demandes de l’API Graph effectuées avec un token d’accès utilisateur·ice sont comptabilisées dans le volume des appels de cet·te utilisateur·ice. Le volume d’appels d’un·e utilisateur·ice correspond au nombre d’appels qu’il ou elle peut effectuer durant une période d’une heure. Par souci de confidentialité, nous ne révélons pas les valeurs réelles de comptage des appels pour les utilisateur·ices.

Notez que le volume d’appels d’un·e utilisateur·ice peut être réparti sur plusieurs applications. Par exemple, un·e utilisateur·ice peut effectuer X appels à partir d’une App1 et Y appels à partir d’une App2. Si X+Y dépasse le volume d’appels de l’utilisateur·ice, ce dernier ou cette dernière est soumis·e au plafond. Cela ne signifie pas nécessairement qu’une application effectue une mauvaise action. Il se peut que l’utilisateur·ice utilise plusieurs applications ou qu’il ou elle fasse un mauvais usage de l’API.

En-têtes

Les points de terminaison qui reçoivent suffisamment de demandes de votre application incluent un en-tête HTTP X-App-Usage ou X-Ad-Account-Usage (pour les appels d’API Ads version 3.3 et antérieures) dans leurs réponses. L’en-tête contient alors une chaîne au format JSON qui décrit l’utilisation actuelle du plafond de l’application.

Contenus de l’en-tête

Contenus de l’en-tête X-Ad-Account-Usage

Temps CPU total

Durée du temps CPU pour le traitement de la demande. Lorsque total_cputime atteint 100, les appels peuvent être régulés.

Temps total

Durée de traitement de la demande. Lorsque total_time atteint 100, les appels peuvent être régulés.

Exemple de valeur d’en-tête X-App-Usage

x-app-usage: {
    "call_count": 28,         //Percentage of calls made 
    "total_time": 25,         //Percentage of total time
    "total_cputime": 25       //Percentage of total CPU time
}

Exemple de valeur d’en-tête X-Ad-Account-Usage

x-ad-account-usage: {
    "acc_id_util_pct": 9.67,   //Percentage of calls made for this ad account.
    "reset_time_duration": 100,   //Time duration (in seconds) it takes to reset the current rate limit score.
    "ads_api_access_tier": 'standard_access'   //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting.
}

Tableau de bord

L’Espace App affiche le nombre d’utilisateur·ices de l’application plafonnée, le pourcentage d’utilisation actuelle de cette dernière, ainsi que l’activité moyenne des 7 derniers jours. Dans la carte Plafond d’application, cliquez sur Voir les détails et survolez n’importe quel point du graphe pour afficher plus de détails sur l’utilisation à ce moment précis. Comme l’utilisation dépend du volume d’appels, ce graphe peut ne pas indiquer l’intégralité de la période de 7 jours. Les applications avec un volume d’appels plus important présenteront plus de jours.

Codes d’erreur

Lorsqu’une application ou un·e utilisateur·ice a atteint son plafond, les demandes effectuées par cette application ou cet·te utilisateur·ice sont honorées et l’API répond avec un code d’erreur.

Codes d’erreur de limitation de bande passante

Exemple de réponse

{
  "error": {
    "message": "(#32) Page request limit reached",
    "type": "OAuthException",
    "code": 32,
    "fbtrace_id": "Fz54k3GZrio"
  }
}

Codes de limitation de bande passante pour la stabilité de Facebook

Recommandations

• Lorsque le plafond est atteint, cessez d’effectuer des appels d’API. Sinon, votre volume d’appels continuera d’augmenter, ce qui repoussera le moment où les appels aboutiront de nouveau.
• Répartissez les requêtes de façon homogène pour éviter les pics de trafic.
• Utilisez des filtres pour limiter la taille des données de réponse et éviter les appels demandant que les données se chevauchent.
• Vérifiez l’en-tête HTTP X-App-Usage pour savoir si votre application est proche de son plafond et, lorsque le plafond est atteint, savoir quand vous pourrez reprendre vos appels.
• Si vos utilisateur·ices sont régulé·es, assurez-vous que votre application n’en est pas la cause. Réduisez les appels de l’utilisateur·ice ou répartissez ses appels plus uniformément dans le temps.

Plafonds Business Use Case

Toutes les requêtes de l’API Marketing et de l’API Pages effectuées avec un token d’accès système ou de Page sont soumises à des plafonds BUC (Business Use Case) et dépendent des points de terminaison que vous interrogez.

Pour l'API Marketing, le plafond est appliqué au compte publicitaire au sein du même BUC. Par exemple, tous les points de terminaison ayant le BUC de gestion des publicités partagent le quota total du compte publicitaire associé. Si un point de terminaison effectue un grand nombre de requêtes d’API et provoque une limitation de bande passante, les autres points de terminaison qui partagent le même BUC recevront eux aussi des erreurs liées à la limitation de bande passante. Le quota dépend du niveau d’accès de l’application à l’API Marketing. Le niveau d’accès standard à l’API Marketing dispose d’un quota plus élevé que le niveau d’accès de développement. Par défaut, les nouvelles applications doivent être au niveau de développement. Si vous souhaitez disposer d’un plafond plus élevé, passez de l’accès standard à la gestion des publicités à l’accès Avancé dans le Contrôle app.

Insights publicitaires

Les requêtes que votre application envoie à l'API Ads Insights sont comptabilisées dans les indicateurs de plafond de l’application, par exemple le nombre d'appels, le temps CPU total et le temps total. Le nombre d'appels d'une application est le nombre d'appels que celle-ci peut effectuer pendant une fenêtre continue d’une heure, et il est calculé comme suit :

Pour les applications disposant de l’accès standard à la fonctionnalité d’accès standard à la gestion des publicités :

Pour les applications disposant de l’accès Avancé à la fonctionnalité d’accès standard à la gestion des publicités :

Le nombre de publicités actives correspond au nombre de publicités associées à chaque compte publicitaire. Les erreurs utilisateur·ice correspondent au nombre d’erreurs reçues lors de l’appel de l’API. Pour obtenir un plafond supérieur, vous pouvez demander la fonctionnalité Accès standard à la gestion des publicités.

Le plafond peut également être soumis au temps CPU total et au temps d’exécution total pendant une fenêtre continue d’une heure. Pour plus d’informations, consultez les propriétés total_cputime et total_time de l’en-tête HTTP X-Business-Use-Case.

Si vous recevez des erreurs relatives au plafond, vous pouvez également consulter la propriété estimated_time_to_regain_access de l'en-tête X-Business-Use-Case pour connaître le temps de blocage estimé.

Gestion des publicités

Les requêtes que votre application envoie à l'API Ads Management sont comptabilisées dans les indicateurs de plafond de l'application, par exemple le nombre d'appels, le temps CPU total et le temps total. Le nombre d'appels d'une application est le nombre d'appels que celle-ci peut effectuer pendant une fenêtre continue d’une heure, et il est calculé comme suit :

Pour les applications disposant d’un accès standard à la fonctionnalité d’accès standard à la gestion des publicités :

Pour les applications disposant de l’accès Avancé à la fonctionnalité d’accès standard à la gestion des publicités :

Le nombre de publicités actives correspond au nombre de publicités associées à chaque compte publicitaire.

Le plafond peut également être soumis au temps CPU total et au temps d’exécution total pendant une fenêtre continue d’une heure. Pour plus d’informations, consultez les propriétés total_cputime et total_time de l’en-tête HTTP X-Business-Use-Case.

Si vous recevez des erreurs relatives au plafond, vous pouvez également consulter la propriété estimated_time_to_regain_access de l'en-tête X-Business-Use-Case pour connaître le temps de blocage estimé.

Catalogue

Lot de catalogues

Les requêtes que votre application envoie sont comptabilisées dans les indicateurs de plafond, par exemple le nombre d'appels, le temps CPU total et le temps total dont votre application dispose au cours d’une période continue d’une heure pour chaque ID de catalogue, qui est calculé comme suit :

Les utilisateur·ices uniques correspondent au nombre d’utilisateur·ices uniques de l’entreprise (sur tous les catalogues) ayant eu une intention d’achat au cours des 28 derniers jours. Plus le nombre d’utilisateur·ices consultant les produits de votre catalogue est important, plus le quota d’appels alloué est élevé.

Gestion des catalogues

Les requêtes émanant de votre application sont décomptées du nombre d’appels qu’elle peut effectuer sur une période d’une heure par ID de catalogue. Le calcul s’effectue de la manière suivante :

Les utilisateur·ices uniques correspondent au nombre d’utilisateur·ices uniques de l’entreprise (sur tous les catalogues) ayant eu une intention d’achat au cours des 28 derniers jours. Plus le nombre d’utilisateur·ices consultant les produits de votre catalogue est important, plus le quota d’appels alloué est élevé.

Cette formule est appliquée à plusieurs points de terminaison du catalogue.

Pour connaître le niveau actuel d’utilisation de votre quota, consultez la section En-têtes.

Le plafond peut également être soumis au temps CPU total et au temps d’exécution total pendant une fenêtre continue d’une heure. Pour plus d’informations, consultez les propriétés total_cputime et total_time de l’en-tête HTTP X-Business-Use-Case.

Si vous recevez des erreurs relatives au plafond, vous pouvez également consulter la propriété estimated_time_to_regain_access de l'en-tête X-Business-Use-Case pour connaître le temps de blocage estimé.

Audience personnalisée

Les requêtes que votre application envoie à l'API Custom Audience sont comptabilisées dans les indicateurs de plafond de l’application, par exemple le nombre d'appels, le temps CPU total et le temps total. Le nombre d’appels d’une application correspond au volume d’appels qu’elle peut effectuer durant une période continue d’une heure, calculé comme suit, sans jamais dépasser les 700 000 :

Pour les applications disposant de l’accès standard à la fonctionnalité d’accès standard à la gestion des publicités :

Pour les applications disposant de l’accès Avancé à la fonctionnalité d’accès standard à la gestion des publicités :

Le nombre d’audiences personnalisées actives correspond au nombre d’audiences personnalisées actives associées à chaque compte publicitaire.

Le plafond peut également être soumis au temps CPU total et au temps d’exécution total pendant une fenêtre continue d’une heure. Pour plus d’informations, consultez les propriétés total_cputime et total_time de l’en-tête HTTP X-Business-Use-Case.

Si vous recevez des erreurs relatives au plafond, vous pouvez également consulter la propriété estimated_time_to_regain_access de l'en-tête X-Business-Use-Case pour connaître le temps de blocage estimé.

API Graph pour Instagram

Les appels de l’API Graph pour Instagram sont comptabilisés dans le volume des appels de l’application appelante. Le volume d’appels d’une application, qui est unique pour chaque paire application/utilisateur·ice, correspond au nombre d’appels que l’application a passé dans une période de 24 heures. Il est calculé comme suit :

Le nombre d’impressions est le nombre de fois où un contenu provenant du compte Instagram de l’utilisateur·ice de l’application est entré à l’écran d’une personne au cours des dernières 24 heures.

Remarques

• L’API Basic Display pour Instagram utilise les Plafonds de plateforme.
• Business Discovery et Hashtag Search obéissent aux Plafonds de plateforme.

LeadGen

Les demandes envoyées par votre application à l’API LeadGen sont comptabilisées dans son volume d’appels. Le volume d’appels d’une application correspond au nombre d’appels qu’elle peut effectuer durant une période donnée de 24 heures, calculé comme suit :

Le nombre de prospects générés est le nombre de prospects générés par Page pour ce compte publicitaire au cours des 90 derniers jours.

Plateforme Messenger

Pages

Les plafonds de Page peuvent utiliser la logique de plafond de plateforme ou BUC en fonction du type de token utilisé. Ces appels de l’API Pages qui sont effectués à l’aide d’un token d’accès de Page ou d’un token d’accès utilisateur·ice système utilisent le calcul de plafond ci-dessous. Les appels effectués à l’aide de tokens d’accès d’application ou tokens d’accès utilisateur·ice sont soumis aux plafonds d’application ou Utilisateur·ice.

Les requêtes envoyées par votre application à l’API Pages à l’aide d’un token d’accès de Page ou d’un token d’accès d’utilisateur·ice système sont comptabilisées dans le volume d’appels de l’application. Le volume d’appels d’une application correspond au nombre d’appels qu’elle peut effectuer durant une période donnée de 24 heures, calculé comme suit :

Le nombre d’utilisateur·ices impliqué·es correspond au nombre d’utilisateur·ices ayant interagi avec la Page au cours d’une période de 24 heures.

Les demandes effectuées par votre application à l’API Pages à l’aide d’un token d’accès utilisateur·ice ou d’un token d’accès Application suivent la logique de plafond de plateforme.

Pour éviter que des problèmes de plafond ne se produisent lorsque vous utilisez la fonctionnalité Contenu d’accès public de Page, il est recommandé d’utiliser un token d’accès d’utilisateur·ice système.

Gestion des effets Commerce Spark AR

Les demandes envoyées par votre application aux points de terminaison Commerce sont comptabilisées dans son volume d’appels. Le volume d’appels d’une application correspond au nombre d’appels qu’elle peut effectuer durant une période donnée (une heure), calculé comme suit :

Le nombre de catalogues correspond au nombre total de catalogues sur l’ensemble des comptes marchands gérés par votre application.

API WhatsApp Business Management

En-têtes

Toutes les réponses d’API produites par votre application qui sont plafonnées à l’aide de la logique BUC comprennent un en-tête HTTP X-Business-Use-Case-Usage (pour les appels de l’API Ads version 3.3 et antérieures) avec une chaîne au format JSON qui décrit l’utilisation actuelle du plafond de l’application. Cet en-tête peut retourner jusqu’à 32 objets par appel.

Contenu de l’en-tête X-Business-Use-Case-Usage

Temps CPU total

Durée du temps CPU pour le traitement de la requête. Lorsque total_cputime atteint 100, les appels peuvent être régulés.

Temps total

Durée de traitement de la requête. Lorsque total_time atteint 100, les appels peuvent être régulés.

Niveau d’accès aux API publicitaires

Uniquement pour les types ads_insights et ads_management. Les niveaux permettent à votre application d’accéder à l’API Marketing. Par défaut, les applications sont dans le niveau development_access. Standard_access octroie un plafond inférieur. Pour obtenir un plafond supérieur et accéder au niveau standard, demandez un accès Avancé (« Advanced Access ») à la fonctionnalité Accès standard à la gestion des publicités.

Valeur de l’en-tête X-Business-Use-Case-Usage

x-business-use-case-usage: {
    "{business-object-id}": [
        {
            "type": "{rate-limit-type}",           //Type of BUC rate limit logic being applied.
            "call_count": 100,                     //Percentage of calls made. 
            "total_cputime": 25,                   //Percentage of the total CPU time that has been used.
            "total_time": 25,                      //Percentage of the total time that has been used.   
            "estimated_time_to_regain_access": 19,  //Time in minutes to regain access.
            "ads_api_access_tier": "standard_access"  //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting.
        }
    ],      
    "66782684": [
        {
            "type": "ads_management",
            "call_count": 95,
            "total_cputime": 20,
            "total_time": 20,
            "estimated_time_to_regain_access": 0,
            "ads_api_access_tier": "development_access" 
        }
    ],
    "10153848260347724": [
        {
            "type": "ads_insights",
            "call_count": 97,
            "total_cputime": 23,
            "total_time": 23,
            "estimated_time_to_regain_access": 0,
            "ads_api_access_tier": "development_access"
        }
    ],
    "10153848260347724": [
        {
            "type": "pages",
            "call_count": 97,
            "total_cputime": 23,
            "total_time": 23,
            "estimated_time_to_regain_access": 0
        }
    ],
...
}

Codes d’erreur

Lorsque votre application atteint son plafond BUC, les demandes ultérieures qu’elle effectue échouent et l’API renvoie un code d’erreur.

Exemple de message de code d’erreur

{   
"error": {      
    "message": "(#80001) There have been too many calls to this Page account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.",      
    "type": "OAuthException",      
    "code": 80001,      
    "fbtrace_id": "AmFGcW_3hwDB7qFbl_QdebZ"   
    }
}

Recommandations

• Lorsque le plafond est atteint, cessez d’effectuer des appels d’API. Continuer à passer des appels continuera d’augmenter votre volume d’appels, ce qui repoussera le moment où les appels aboutiront de nouveau.
• Vérifiez l’en-tête HTTP X-Business-Use-Case-Usage pour savoir si votre compte publicitaire est proche de son plafond et quand vous pourrez reprendre vos appels.
• Vérifiez le code d’erreur et le point de terminaison de l’API pour confirmer le type de limitation de bande passante.
• Basculez sur les autres comptes publicitaires et revenez sur ce compte ultérieurement.
• Il est préférable de créer une publicité plutôt que de modifier les publicités existantes.
• Répartissez les requêtes uniformément entre deux intervalles de temps afin d’éviter d’envoyer le trafic par pics.
• Utilisez des filtres pour limiter la taille des données de réponse et éviter les appels demandant des données qui se recoupent.

Questions/réponses

Que considérons-nous comme un appel d’API ?

Tous les appels sont comptabilisés dans les plafonds, pas seulement les demandes d’API individuelles. Par exemple, vous pouvez passer un appel d’API unique en indiquant plusieurs ID mais chaque ID compte pour un appel d’API.

Le tableau suivant illustre ce concept.

Nous vous recommandons vivement de spécifier plusieurs ID dans une demande d’API lorsque cela est possible, car cela améliore les performances de vos réponses d’API.

Je crée un scraper. À quoi d’autre dois-je faire attention ?

Si vous créez un service qui extrait des données, veuillez lire nos conditions générales d’extraction.