Chez Meta, l'en-tête x-app-usage donne trois pourcentages et aucune horloge

Qu'est-ce que l'en-tête x-app-usage ?

Meta renvoie l'en-tête x-app-usage sur les réponses de la Graph API pour indiquer à une application quelle part de sa propre limite de débit elle a déjà dépensée. La référence sur la limitation de débit le présente en une phrase : « Endpoints that receive enough requests from your app will include a X-App-Usage or X-Ad-Account-Usage (for v3.3 and older Ads API calls) HTTP header in their responses. The header will contain a JSON-formatted string that describes current application rate limit usage. »

Deux conditions se cachent dans cette phrase. L'en-tête appartient à l'application, pas au compte ni à l'utilisateur dont le jeton a fait l'appel. Et il n'arrive que sur les endpoints qui ont vu assez de trafic, ce que Meta reformule ailleurs en disant que les en-têtes sont « included with most API responses once enough calls have been made to an endpoint. » Une réponse sans x-app-usage signifie que Meta a renoncé à rapporter, pas que la consommation est nulle.

La valeur est un objet JSON à trois clés, et rien d'autre. L'exemple de Meta :

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
}

Savoir quelles requêtes reçoivent cet en-tête plutôt qu'un autre dépend de l'API et du jeton. Meta tranche nettement : « Graph API requests are subject to Platform Rate Limits, while Marketing API and Instagram Platform requests are subject to Business Use Case (BUC) Rate Limits. » Les appels à l'API Pages tombent d'un côté ou de l'autre selon les identifiants, les jetons d'accès application et utilisateur du côté Platform, les jetons d'utilisateur système ou de Page du côté business use case.

Que signifient les trois champs de x-app-usage ?

Tous trois sont des pourcentages d'un quota, pas des décomptes.

Le mot « whole » travaille pour de vrai. Chaque valeur de x-app-usage est un entier, donc la lecture la plus fine que vous obteniez vaut un pour cent du budget. L'autre en-tête de Meta au niveau application est plus précis sur la même idée : le champ acc_id_util_pct de X-Ad-Account-Usage apparaît dans l'exemple sous la forme 9.67, avec des décimales. x-app-usage arrondit.

Les trois champs limitent aussi indépendamment les uns des autres. Meta accroche les deux mêmes lignes aux deux champs de temps : « When total_cputime reaches 100, calls may be throttled » et « When total_time reaches 100, calls may be throttled. » Une poignée de requêtes coûteuses peut pousser total_cputime vers le plafond pendant que call_count en est encore aux unités, donc une application qui ne surveille que le volume d'appels rate deux des trois façons de se faire bloquer.

Remarquez ce que Meta ne publie pas à cet endroit. La référence énonce un seuil pour total_cputime et un seuil pour total_time, et n'écrit jamais la phrase équivalente pour call_count dans la section des en-têtes Platform. Ce qu'elle dit à la place reste général : « Once a rate limit is reached, any subsequent requests made by your app will fail and the API will return an error code until enough time has passed for the call count to drop below the limit. » Lisez quand même 100 sur call_count comme la limite, puisque rien dans le document ne suggère un autre nombre.

À quel quota les pourcentages se rapportent-ils ?

À une formule au niveau de l'application, que Meta publie en entier : Calls within one hour = 200 * Number of Users.

Le multiplicateur est fixe et le multiplicande est l'engagement. Meta le définit comme « the number of unique daily active users an app has », avec un repli pour le trafic irrégulier : « In cases where there are slow periods of daily usage, such as if your app has high activity on weekends but low activity over weekdays, the weekly and monthly active Users are used to calculate the number of Users for your app. » Les installations n'entrent pas dans le calcul. Meta le dit directement : les applications à fort engagement quotidien obtiennent des limites plus hautes « regardless of the actual number of app installs. »

Le réservoir est partagé, pas divisé. Meta fait le calcul lui-même : « if your app has 100 Users, your app can make 20,000 calls per hour. However, your top ten most engaged Users could make 19,000 of those calls. » Un seul compte bruyant peut affamer le reste des utilisateurs d'une application dans la même heure, et rien dans la limite Platform ne l'en empêche.

Les jetons utilisateur portent un second décompte, distinct, qu'aucun en-tête ne rapporte. Le décompte d'appels d'un utilisateur tourne sur sa propre heure glissante et couvre toutes les applications qu'il utilise, si bien que Meta prévient qu'un utilisateur « could make X calls through App1 and Y calls through App2 » et se fera limiter sur le total. Puis elle ferme la porte à toute mesure : « Due to privacy concerns, we do not reveal actual call count values for users. » Il n'existe pas d'en-tête x-user-usage. Le versant utilisateur des Platform Rate Limits est inobservable par construction.

Une règle de comptage piège ceux qui regroupent leurs appels. La FAQ de Meta indique que « each ID counts as one API call » et le démontre : trois requêtes séparées à un identifiant comptent pour trois appels, et une requête unique avec ids=4,5,6 compte aussi pour trois. Le regroupement améliore le temps de réponse et n'achète aucun quota. C'est un modèle de comptabilité différent de celui des plafonds de requêtes par endpoint publiés par Bluesky et de la séparation entre plafonds application et utilisateur chez Pinterest.

En quoi x-app-usage diffère-t-il de l'en-tête business use case ?

Portée différente, forme différente, et l'un des deux vous dit quand vous êtes de nouveau admis.

L'en-tête business use case est le plus riche des deux, et c'est celui qui compte pour le travail de publication sur Instagram. La formule 4800 fois les impressions de Meta et les champs de X-Business-Use-Case-Usage sont traités en détail à part, y compris les valeurs de type et les codes d'erreur rattachés à chacune.

Là où les deux en-têtes se touchent, le document de Meta se contredit lui-même. La section Platform accroche la parenthèse « (for v3.3 and older Ads API calls) » à X-Ad-Account-Usage, ce qu'elle décrit bien. La section business use case répète ensuite la même parenthèse sur un autre en-tête : « All API responses made by your app that are rate limited using the BUC logic include an X-Business-Use-Case-Usage (for v3.3 and older Ads API calls) HTTP header. » L'en-tête business use case n'est pas réservé aux appels v3.3 et antérieurs, et le reste de cette même section le documente comme le mécanisme actuel pour le trafic Instagram et Marketing API. Traitez ce qualificatif comme un copier-coller resté en place.

La règle de priorité entre les deux est la ligne à retenir : « If both Platform and Business Use Case rate limits can be applied to a request, BUC rate limits will be applied. »

Que se passe-t-il quand x-app-usage affiche 100 ?

Les appels commencent à échouer avec une erreur numérotée, et le numéro dépend de la limite qui a cédé.

La consigne de Meta est la même pour toutes, et ce n'est pas une politique de backoff : « When the limit has been reached, stop making API calls. Continuing to make calls will continue to increase your call count, which will increase the time before calls will be successful again. »

C'est la phrase que la plupart des boucles de réessai comprennent de travers. Le backoff exponentiel envoie quand même des requêtes, et selon Meta chacune repousse encore le moment du déblocage. La bonne réaction au code d'erreur 4 est de garer la file, pas de la ralentir.

Vient ensuite le trou. La bonne pratique de Meta pour se rétablir dit : « Check the X-App-Usage HTTP header to see how close your app is to its limit and when you can resume making calls when the limit has been reached. » L'en-tête a trois champs, tous des pourcentages, et aucun n'est un temps. estimated_time_to_regain_access existe sur l'en-tête business use case. reset_time_duration existe sur X-Ad-Account-Usage. Ni l'un ni l'autre n'existe sur x-app-usage. Meta vous demande de lire une heure de reprise dans un en-tête qui n'en porte aucune.

Ce que vous obtenez à la place, c'est l'App Dashboard, où Meta affiche « the app's current Application Rate Limits usage percentage » et l'activité moyenne des sept derniers jours. C'est un graphique pour humains, pas un champ que votre logique de réessai peut lire. L'approche pratique consiste à regarder call_count grimper, à s'arrêter bien avant 100 et à répartir le trafic uniformément, ce qui est aussi le conseil affiché de Meta : « Spread out queries evenly to avoid traffic spikes. » Les calendriers de publication se heurtent en plus à des plafonds distincts et non chiffrés, et les limites quotidiennes de publication de Facebook forment leur propre système avec leur propre comportement.

Questions fréquentes

Quels sont les trois champs de l'en-tête x-app-usage ?

call_count, total_cputime et total_time. Meta définit chacun comme un nombre entier exprimant un pourcentage, des appels effectués sur une heure glissante d'une part, du temps CPU et du temps total alloués au traitement des requêtes d'autre part.

Quelle est la limite de débit Graph API au niveau application derrière call_count ?

Calls within one hour = 200 * Number of Users, où le nombre d'utilisateurs correspond au décompte Meta des utilisateurs actifs quotidiens uniques de l'application, avec un repli sur les actifs hebdomadaires et mensuels quand le trafic quotidien est irrégulier.

Quel code d'erreur signale que la limite x-app-usage a été atteinte ?

Le code d'erreur 4, que Meta nomme « API Too Many Calls ». Le code 17 couvre la limite propre à l'utilisateur, et le code 32 couvre les appels à l'API Pages faits avec un jeton d'accès utilisateur ou application.

x-app-usage indique-t-il quand le blocage prend fin ?

Non. Il porte trois pourcentages et aucun champ de temps, alors même que les bonnes pratiques de Meta vous disent de le consulter pour savoir quand reprendre. estimated_time_to_regain_access appartient à l'en-tête business use case, pas à celui-ci.

L'en-tête x-app-usage apparaît-il sur chaque réponse ?

Non. Meta le renvoie sur les endpoints « that receive enough requests from your app », donc un en-tête absent ne porte aucune information et ne doit jamais se lire comme une consommation nulle.

Quelles requêtes reçoivent x-app-usage plutôt que X-Business-Use-Case-Usage ?

Les requêtes Graph API soumises aux Platform Rate Limits. Les requêtes Marketing API et Instagram Platform reçoivent l'en-tête business use case, et quand les deux pourraient s'appliquer, Meta indique que les limites business use case l'emportent.

Qu'est-ce qui compte comme utilisateur dans la formule 200 fois utilisateurs ?

Meta le définit comme le nombre d'utilisateurs actifs quotidiens uniques de l'application. Quand le trafic quotidien varie entre semaine et week-end, les utilisateurs actifs hebdomadaires et mensuels sont utilisés à la place. Les installations n'entrent pas en compte, puisque les applications à fort engagement obtiennent des limites plus élevées quel que soit le nombre réel d'installations.

Un seul utilisateur peut-il épuiser toute la limite de débit d'une application ?

Un utilisateur très actif le peut. Meta fait le calcul lui-même : une application avec 100 utilisateurs dispose d'un quota de 20 000 appels par heure, et les dix utilisateurs les plus engagés pourraient en représenter 19 000. Le quota est partagé et non réparti, donc rien dans la limite Platform n'empêche un seul compte de priver les autres utilisateurs de l'application de leur part dans la même heure.

Regrouper plusieurs ID dans une seule requête économise-t-il de la limite de débit ?

Le regroupement ne réduit pas ce qui compte dans le quota. La FAQ de Meta indique que chaque ID compte comme un appel API, donc trois requêtes séparées à un seul ID et une requête avec ids=4,5,6 comptent pareil, comme trois appels. Le batching améliore la performance de la réponse, pas le budget.

En quoi x-app-usage diffère-t-il de X-Ad-Account-Usage ?

X-Ad-Account-Usage rapporte son champ acc_id_util_pct avec des décimales, indiqué dans l'exemple de Meta comme 9,67, alors que chaque champ de x-app-usage est arrondi à un pourcentage entier. X-Ad-Account-Usage inclut aussi reset_time_duration, un champ absent de x-app-usage, et l'en-tête est lié aux appels de l'API Ads en version 3.3 et antérieures.