Limitation de débit sur l’API Graph

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. Votre app recevra le code d’erreur 4 si vous atteignez ces limites.

Tableau de bord de la limitation de débit

Consultez les graphiques de l’activité de votre app au niveau de la limitation de débit sur le tableau de bord de votre app.

Limites

Des limitations de débit sont imposées pour chaque app. L’outil de limitation de débit vous indique si votre application va bientôt être régulée ou pas. Cliquez sur l’un des exemples pour obtenir plus de détails sur les types d’utilisation.

Votre app peut effectuer 200 appels par heure et par utilisateur au total. Par exemple, si votre app a 100 utilisateurs, cela signifie qu’elle peut effectuer 20 000 appels. Il ne s’agit pas d’une limite par utilisateur. Aussi, un utilisateur particulier pourrait faire 19 000 de ces appels et un autre en faire 1 000. Cette limite est calculée en fonction du nombre d’appels effectués au cours de l’heure précédente.

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

Le nombre d’utilisateurs pour votre application est calculé comme le nombre moyen d’utilisateurs actifs quotidiens, plus les nouvelles connexions du jour comme valeur estimée. Les applications avec un grand nombre d’utilisateurs peuvent avoir une limitation de débit plus précise que celles avec un nombre d’utilisateurs inférieur. Les applications avec un nombre d’utilisateurs limité 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. Il est difficile d’atteindre ces limites, donc cela arrive très rarement. Ces informations sont affichées dans le volet des détails pour chaque échantillon. 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 à l’adresse https://developers.facebook.com/docs/marketing-api/api-rate-limiting pour en savoir plus sur l’API Marketing.

Recommandations

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. Lorsqu’une limitation de débit est dépassée, tous les appels d’API depuis une app sont régulés et échouent durant un bref moment. Lorsqu’une app est régulée, le programme appelant reçoit un message d’erreur pour les appels suivants avec error code = 4, CodedException. Une heure peut être nécessaire pour que vos demandes 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 votre app effectue suffisamment d’appels pour que notre système la prenne en compte pour la limitation de débit, nous renvoyons 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 sur votre graphique 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’u 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 ?

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.