Limitation de débit sur l’API Graph

La limitation de débit définit les nombres maximums d’appels d’API qui peuvent être effectués pendant une période donnée. Des limitations de débit sont imposées à toutes les applications.

Les applications qui dépassent excessivement ou constamment leurs limitations de débit peuvent être désactivées.

La limitation de débit dans l’API Graph de Facebook n’a lieu que dans de rares circonstances. Ce document décrit les limites en question ainsi que leur gestion.

Votre app peut atteindre deux principaux types de limitation de débit : la limitation de débit au niveau de l’app et la limitation de débit au niveau de la page.

Limitation de débit au niveau de l’application

Ces limites s’appliquent aux appels passés au moyen de tout token d’accès autre qu’un token d’accès de page.

Tous les appels d’API provenant d’une app et qui sont faits après le dépassement d’une limitation de débit sont régulés et échoueront avec error code = 4, CodedException. La réussite des appels reprendra lorsque l’utilisation au cours de la dernière heure écoulée sera à nouveau en dessous de la limitation. Les limitations sont calculées sur une fenêtre d’une heure glissante et les pourcentages d’utilisation actuels sont disponibles sur votre espace app.

Tableau de bord de la limitation de débit

L’outil de limitation de débit vous indique si votre application va bientôt être régulée ou pas. Vous pouvez consulter des informations sur les limitations de débit concernant vos apps à l’aide de deux graphiques dans l’espace app.

  • Un graphique montre l’utilisation actuelle concernant vos réponses de l’API Graph renvoyées. Il s’agit d’une représentation visuelle de la valeur d’en-tête renvoyée dans les demandes de l’API Graph.
Graphique pour une app qui s’approche de sa limitation de débit
  • Le second graphique montre l’historique des limitations de débit. Vous pouvez choisir d’afficher les données pour les 24 dernières heures ou les 7 derniers jours. Vous pouvez cliquer sur tout échantillon dans le graphique historique pour voir davantage de détails sur l’utilisation, notamment une répartition par méthode. Toutes les applications ne disposent pas de données historiques, car la présence de ces données dépend du volume d’appels. Les applications avec un volume d’appels supérieur sont plus susceptibles de disposer de données historiques.
Graphique historique pour une app dépassant les limites de débit au cours des 24 dernières heures

Limites

Le nombre total d’appels que votre app peut passer par heure est de 200 fois le nombre d’utilisateurs. Il ne s’agit pas d’une limitation par utilisateur. Tout utilisateur individuel peut passer plus de 200 appels par heure, tant que le total pour tous les utilisateurs ne dépasse pas le maximum pour l’app. Par exemple, si votre app a 100 utilisateurs, elle peut effectuer 20 000 appels par heure. Cependant, il est possible que vos dix utilisateurs les plus engagés fassent 19 000 de ces appels.

Lorsque votre app a une limitation de débit, tous les appels qui lui sont adressés sont limités, pas seulement les appels pour un utilisateur particulier.

Le nombre d’utilisateurs pour votre app est calculé à l’aide du nombre d’utilisateurs actifs quotidiens et des nouvelles connexions du jour. En cas de périodes d’utilisation quotidienne faibles, les utilisateurs actifs hebdomadaires, ou même les utilisateurs actifs mensuels, sont utilisés pour calculer le nombre d’utilisateurs de votre app. Les applications avec un engagement quotidien élevé auront des limitations de débit supérieures aux applications avec un engagement quotidien faible, indépendamment du nombre réel d’installations d’app.

Avertissements :

  • Tous les appels d’API ne sont pas soumis aux limitations de débit. Aussi, le nombre d’appels que vous passez peut ne pas correspondre à ce que vous voyez dans l’outil de limitation de débit.
  • Nous régulons aussi les appels en fonction du temps CPU utilisé et du temps total. Les points de terminaison qui nécessitent beaucoup de traitement peuvent faire que votre app atteint ces limitations, malgré qu’elle soit en dessous de la limitation du volume d’appels. Les applications atteignent rarement les limitations du temps CPU et du temps total, sauf pour les points de terminaison spécialisés. Le cas échéant, des informations à propos des points de terminaison qui utilisent beaucoup de temps CPU ou de temps total peuvent être consultées dans le graphique historique.
  • Il est possible que l’API Ads Insights et l’API Marketing utilisent des limitations de débit différentes. N’hésitez pas à consulter le document sur la limitation de débit sur l’API Marketing à l’adresse https://developers.facebook.com/docs/marketing-api/api-rate-limiting pour en savoir plus sur l’API Marketing.

Recommandations

Pour éviter la limitation de débit :

  • répartissez les requêtes uniformément entre deux intervalles de temps afin d’éviter d’envoyer le trafic par pics ;
  • utilisez des filtres afin de limiter la taille des données de réponse et d’éviter les appels qui requièrent que les données se chevauchent ;
  • utilisez l’en-tête de limitation de débit pour équilibrer dynamiquement votre volume d’appels.

En-tête de limitation de débit

Toutes les réponses aux appels faits à l’API Graph comprennent un en-tête HTTP X-App-Usage. Cet en-tête contient le pourcentage d’utilisation actuel pour votre app. Ce pourcentage est égal à l’utilisation indiquée dans vos graphiques de limitation de débit. Utilisez ce chiffre pour équilibrer dynamiquement votre charge d’appels pour éviter la régulation de votre app.

L’en-tête de limitation de débit est une chaîne au format JSON qui a la forme suivante :

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

Les valeurs de x, y et z sont des nombres entiers qui représentent les valeurs d’utilisation en pourcentage pour chacune des mesures. Lorsque l’une de ces mesures dépasse 100, une limitation de débit est appliquée à l’app.

Limitation de débit au niveau de la page

Ces limites s’appliquent aux appels passés au moyen d’un token d’accès de page. Votre app recevra le code d’erreur 32 si vous atteignez ces limites.

L’article de blog à l’adresse https://developers.facebook.com/blog/post/2016/06/16/page-level-rate-limits/ fournit une explication détaillée de la limitation de débit au niveau de la page.

Tableau de bord de la limitation de débit

Pour chaque page dont le token d’accès est utilisé par votre app pour effectuer des appels, vous pouvez voir les graphiques de limitation de débit.

Limites

Les limitations de débit sont imposées sur chaque page, plutôt que sur l’app. L’outil de limitation de débit vous donne des informations sur le nombre d’apps qui utilisent le token d’accès de cette page et si la page est sur le point d’être régulée ou pas. Cliquez sur l’un des exemples pour obtenir plus de détails sur les types d’utilisation.

Le nombre de personnes engagées quotidiennes qui utilisent une page est le nombre unique de personnes qui ont interagi avec la page au cours d’une période de 24 heures. Une interaction avec une page est un clic sur la page ou sur un contenu de la page.

Le nombre d’utilisateurs engagés au cours des 24 heures précédentes est utilisé pour calculer les limitations de débit pour la période de 24 heures actuelle.

Au total, 4 800 appels par utilisateurs engagés quotidiens peuvent être effectués au nom de la page par période de 24 heures au total. Par exemple, si la page compte 100 utilisateurs engagés quotidiens, alors 480 000 appels peuvent être effectués au nom de la page pendant une période de 24 heures. Cette période de 24 heures est une période glissante qui est mise à jour toutes les quelques minutes. La limite d’appels est une limite par page. Aussi, une app particulière pourrait effectuer 400 000 appels et une autre en faire 80 000. Si une page a une limitation de débit, seuls les appels à partir de votre app qui utilisent le token d’accès de cette page seront limités. Cela signifie que votre app peut toujours fonctionner normalement pour d’autres appels.

Le nombre d’appels vers votre Page est calculé comme le nombre estimé d’appels utilisant le token d’accès de votre Page chaque jour. Les Pages avec un grand nombre d’appels par jour peuvent avoir une limitation de débit plus précise que celles présentant un nombre d’appels par jour plus faible. Les Pages avec un nombre d’appels par jour très faible peuvent présenter des problèmes de limitation de débit.

Avertissements :

  • Tous les appels d’API ne sont pas soumis à la limitation de débit. Aussi, le nombre d’appels que vous passez peut ne pas correspondre à ce que vous voyez dans l’outil de limitation de débit.
  • Facebook régule aussi les appels en fonction du temps CPU utilisé et du temps total. Pour obtenir plus de détails, cliquez sur le graphique dans l’outil de limitation de débit sur votre tableau de bord.
  • Il est possible que l’API Ads Insights et l’API Marketing utilisent des limitations de débit différentes. N’hésitez pas à consulter le document sur la limitation de débit sur l’API Marketing pour en savoir plus sur l’API Marketing.

Recommandations

Lorsqu’une page est régulée, le programme appelant reçoit un message d’erreur pour les appels suivants avec error code = 32, CodedException. Une heure peut être nécessaire pour que vos demandes adressées à cette page soient à nouveau acceptées.

Pour éviter la limitation de débit :

  • répartissez les requêtes uniformément entre deux intervalles de temps afin d’éviter d’envoyer le trafic par pics ;
  • utilisez des filtres afin de limiter la taille des données de réponse et d’éviter les appels qui requièrent que les données se chevauchent ;
  • utilisez l’en-tête de limitation de débit pour équilibrer dynamiquement votre volume d’appels.

En-tête de limitation de débit

Si suffisamment d’appels sont effectués au nom d’une page pour que notre système la prenne en compte pour la limitation de débit, nous renvoyons un en-tête HTTP X-Page-Usage. Cet en-tête contient le pourcentage d’utilisation actuel pour votre page. Si vous effectuez des appels au moyen d’un token d’accès d’une page, vous obtenez une valeur X-Page-Usage pour cette page uniquement. Ce pourcentage est égal à l’utilisation affichée sur le graphique de limitation de débit de cette page. Utilisez ce chiffre pour équilibrer dynamiquement votre charge d’appels pour éviter la régulation de votre app.

L’en-tête de limitation de débit est une chaîne au format JSON qui a la forme suivante :

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

Les valeurs de x, y et z sont des nombres entiers qui représentent les valeurs d’utilisation en pourcentage pour chacune des mesures. Lorsque l’une de ces mesures dépasse 100, une limitation de débit est appliquée à l’app.

Limitation de débit au niveau du compte

Ces limites s’appliquent aux appels passés au moyen d’un token d’accès utilisateur. Votre app recevra le code d’erreur 17 si cette limite est atteinte. Cela se produit lorsque le compte d’un utilisateur précis effectue trop d’appels vers l’API.

Remarque :

cela peut comprendre les appels utilisateurs effectués sur de nombreuses apps, sans se limiter à la vôtre.

Lorsqu’un utilisateur est soumis à une limitation de débit, les appels d’API de l’utilisateur sont régulés.

Pour éviter la limitation de débit :

Il n’y a rien à faire. L’utilisateur effectue trop d’appels (peut-être via d’autres apps) et est donc soumis à une limitation de débit. Cependant, si de nombreux utilisateurs d’une même app sont dans cette situation, il est possible que les appels d’API effectués par le biais de cette app soient en cause. Dans ce cas, nous vous conseillons de réduire le nombre d’appels ou de les espacer davantage.

Questions/réponses

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

Tous les appels sont comptés dans les limitations de débit, pas seulement les requêtes d’API HTTPS individuelles. Par exemple, vous pouvez passer un appel d’API unique et indiquer plusieurs ID, mais chacun de ces ID comptera pour un appel d’API, même si vous n’envoyez qu’une seule requête d’API HTTPS.

Pour illustrer ce concept, observez les exemples ci-dessous :

Exemples de requêtes Nombre d’appels d’API

GET https://graph.facebook.com/photos?id=4
GET https://graph.facebook.com/photos?id=5
GET https://graph.facebook.com/photos?id=6

3

GET https://graph.facebook.com/photos?id=4,5,6

3

Dans un scénario où vous devez traiter plusieurs objets par ID, nous vous recommandons fortement d’utiliser la deuxième approche, car elle améliorera l’efficacité de vos réponses d’API sans pour autant augmenter le nombre d’appels passés, ce qui peut éviter d’atteindre la limitation de débit.

Vous pouvez également utiliser l’API Batch afin de grouper vos requêtes, mais n’oubliez pas que chaque sous-requête constitue un appel d’API et même plusieurs appels d’API si vous indiquez plusieurs ID.

Si votre app ou votre page voit son débit limité, les appels d’API qui rencontrent des erreurs de limitation de débit sont également comptés dans la limite de débit.


Quelles erreurs mon app verra-t-elle ?
Type de régulation Au moins Code d’erreur

Régulation au niveau de l’application

200 appels/personne/heure

4

Régulation au niveau du compte

Sans objet

17

Régulation au niveau de la page

4 800 appels/personne/24 heures

32

Régulation au niveau de la personnalisation

Sans objet

613


Le code d’erreur 613 s’affiche, que dois-je faire ?

Si votre réponse indiquant une erreur contient error_subcode 1996, Facebook a détecté un comportement incohérent dans le volume de demandes d’API de votre app. Vous risquez de rencontrer cette erreur si vous avez récemment apporté des modifications qui ont un impact sur le nombre de demandes d’API.

Si le sous-code ne s’affiche pas, votre app dépasse une limite de débit personnalisée. Veuillez contacter votre gestionnaire des partenaires pour résoudre ce problème.


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

Si vous créez un service qui récupère des données, lisez nos règles en matière de récupération.