Ce que renvoie l'endpoint content_publishing_limit d'Instagram

Que renvoie l'endpoint content_publishing_limit ?

L'endpoint content_publishing_limit de Meta renvoie le nombre de conteneurs qu'un compte professionnel Instagram a déjà publiés dans une fenêtre glissante de 24 heures, avec le plafond auquel ce nombre est comparé. C'est un endpoint en lecture seule. La référence le dit deux fois : « Creating: This operation is not supported » et la même ligne pour la mise à jour et la suppression.

La forme de la requête, copiée de la référence de Meta :

GET https://graph.facebook.com/<API_VERSION>/<IG_USER_ID>/content_publishing_limit
  ?fields=<LIST_OF_FIELDS>
  &since=<UNIX_TIMESTAMP>
  &access_token=<ACCESS_TOKEN>

Les applications bâties sur Instagram API with Instagram Login envoient le même appel à graph.instagram.com à la place. La réponse est un tableau data contenant un seul objet :

{
  "data": [
    {
      "quota_usage": 2,
      "config": {
        "quota_total": 50,
        "quota_duration": 86400
      }
    }
  ]
}

Que veulent dire quota_usage, quota_total et quota_duration ?

Trois noms de champs portent toute la réponse, et Meta définit chacun en une phrase.

quota_usage est le champ que vous obtenez sans rien demander. La note de Meta sur le paramètre fields dit : « A comma-separated list of fields you want returned. If omitted, the quota_usage field will be returned by default. » Demandez config explicitement ou vous ne verrez pas le plafond, seulement le comptage.

Le paramètre since resserre la fenêtre. Meta le décrit comme « A Unix timestamp no older than 24 hours », et ajoute que « If the since parameter is omitted, this value will be the number of times the app user has published a container within the last 24 hours. » Vous ne pouvez pas remonter plus d'une journée, ce qui revient à dire que l'endpoint n'a aucune mémoire au-delà du quota qu'il applique.

Une bizarrerie se niche dans l'exemple de requête de Meta. Il interroge fields=quota_usage,rate_limit_settings, et rate_limit_settings n'apparaît ni dans le tableau des champs de cette page ni ailleurs dans la référence Instagram Platform. L'exemple demande un champ que la documentation ne définit jamais.

Le plafond est-il de 50 posts ou de 100 ?

Meta publie les deux nombres sur des pages en ligne, et ne les réconcilie jamais. Le guide de publication de contenu énonce : « Instagram accounts are limited to 100 API-published posts within a 24-hour moving period. » La référence de content_publishing_limit énonce que quota_total vaut « currently 50 ». La section carrousel de ce même guide énonce : « Accounts are limited to 50 published posts within a 24-hour period. »

Le guide se contredit donc en interne, et la référence penche pour le nombre le plus bas. Ce n'est pas une page périmée que Meta aurait oubliée, c'est la documentation de l'endpoint pour le champ exact qui rapporte le plafond. L'écart entre la phrase des 100 posts et celle des 50 posts est assez ancien pour avoir survécu à plusieurs versions de la Graph API.

La résolution pratique consiste à cesser de lire l'un ou l'autre nombre et à lire quota_total dans la réponse à la place. C'est le nombre auquel le compte est réellement comparé, il arrive par compte, et il coûte une requête à obtenir.

Qu'est-ce qui compte dans le quota et qu'est-ce qui n'y compte pas ?

Publier compte. Créer, non. La distinction est exacte dans la formulation de Meta, puisque quota_usage compte « the number of times the app user has published an IG Container », et le guide nomme l'endpoint où s'applique la règle : « This limit is enforced on the POST /<IG_ID>/media_publish endpoint when attempting to publish a media container. »

La création de conteneurs a son propre plafond que la plupart des équipes n'atteignent jamais. La référence de l'endpoint media énonce : « An Instagram account can only create 400 containers within a rolling 24 hour period. » Huit conteneurs par publication est un rapport généreux, donc un flux qui relance agressivement la création de conteneurs peut épuiser ce budget alors que quota_usage affiche encore zéro, et l'échec ne ressemblera en rien à une limite de fréquence de publication.

Les carrousels sont le cas à intégrer si vous traitez des lots d'images. Dix images deviennent une unité de quota, ce qui rend la planification de posts carrousel sur Instagram et Facebook bien moins coûteuse face au plafond que dix posts simples portant les mêmes images.

Comment lire la réponse avant de publier ?

Appelez content_publishing_limit avant la publication, pas après l'échec, et comparez quota_usage à config.quota_total plutôt qu'à un nombre écrit en dur. Meta le demande directement : « We recommend that your app also enforce the publishing rate limit, especially if your app allows app users to schedule posts to be published in the future. »

Trois détails décident si cette vérification vaut quelque chose :

• Demandez config explicitement. Sans lui, vous obtenez un comptage d'usage et rien à quoi le comparer.
• Traitez la fenêtre comme glissante, pas comme journalière. quota_duration vaut 86400 secondes mesurées à rebours depuis maintenant, la capacité revient donc progressivement au fil de la journée plutôt qu'à une heure de remise à zéro.
• Relisez avant chaque publication d'un lot, pas une fois par lot. Une file de 20 posts qui a vérifié le quota une seule fois au départ est une file qui peut dépasser le plafond au post 14.

C'est sur les outils de planification que cela mord le plus fort, parce qu'une file s'engage sur des heures de publication des heures ou des jours à l'avance alors que le quota se dépense au présent. C'est la même classe de problème que toute API de planification bâtie sur un quota de plateforme : le calendrier est écrit contre une capacité qui n'a pas encore été mesurée.

Quelle erreur Instagram renvoie-t-il quand vous atteignez le plafond ?

La référence des codes d'erreur de Meta la liste précisément. Un compte qui a épuisé son quota de publication reçoit un HTTP 400, code 9, sous-code 2207042, avec le message utilisateur : « You reached maximum number of posts that is allowed to be published by Content Publishing API. »

La solution recommandée dit : « The app user has reached their daily publishing limit. Advise the app's user to try again the following day. » Notez le décalage. La fenêtre est documentée comme une période glissante de 24 heures partout ailleurs, et le conseil parle ici de « the following day », langage de calendrier pour une fenêtre glissante. La capacité se libère 24 heures après chaque publication individuelle, pas à minuit.

Les échecs voisins ont une autre allure et doivent être traités séparément. Le code 4, sous-code 2207051 renvoie « We restrict certain activity to protect our community. Tell us if you think we made a mistake », que Meta attribue à une publication « suspected to be spam ». Ce n'est pas un problème de quota, et réessayer demain ne le réglera pas. D'autres plateformes tracent la même ligne entre un quota que l'on peut attendre et une restriction que l'on ne peut pas, et c'est pourquoi les limites de fréquence publiées de Pinterest et celles d'Instagram ont chacune besoin de chemins de traitement distincts dans la même file.

Quelles permissions l'appel exige-t-il ?

Les portées du jeton diffèrent selon le flux de connexion, et Meta liste les deux. Instagram API with Instagram Login exige instagram_business_basic et instagram_business_content_publish. Instagram API with Facebook Login exige instagram_basic, instagram_content_publish et pages_read_engagement, plus ads_management ou ads_read quand « the app user was granted a role via the Business Manager on the Page connected to the targeted IG User ».

Ce sont les mêmes portées que l'appel de publication lui-même exige, donc un jeton qui peut publier peut aussi lire le quota. Il n'existe pas de portée en lecture seule moins chère pour vérifier la capacité, ce qui veut dire que la vérification du quota est accessible à toute application qui en aurait un jour besoin.

Questions fréquentes

Quel est le chemin complet de l'endpoint ?

GET /<IG_USER_ID>/content_publishing_limit, sur graph.facebook.com pour Instagram API with Facebook Login et sur graph.instagram.com pour Instagram API with Instagram Login.

L'endpoint renvoie-t-il la limite par défaut ?

Non. Seul quota_usage revient par défaut. La référence de Meta indique que l'objet config, qui porte quota_total et quota_duration, doit être demandé via le paramètre fields.

Jusqu'où le paramètre since peut-il remonter ?

24 heures. Meta décrit la valeur comme « A Unix timestamp no older than 24 hours », l'endpoint ne peut donc rapporter aucun usage d'une fenêtre antérieure.

Les tentatives de publication ratées comptent-elles dans quota_usage ?

Meta ne le dit pas. Le champ compte les fois où l'utilisateur « has published an IG Container », ce qui se lit comme des publications réussies, mais la documentation n'aborde jamais le cas d'une publication qui échoue après avoir été acceptée.

Créer un conteneur média consomme-t-il du quota ?

Non. La création de conteneurs est régie par une règle distincte, selon laquelle un compte « can only create 400 containers within a rolling 24 hour period », et les conteneurs expirent après 24 heures qu'ils soient publiés ou non.

Pourquoi quota_total indique-t-il 50 quand le guide indique 100 ?

Meta publie les deux nombres et ne les tranche jamais. La référence de l'endpoint dit que quota_total vaut « currently 50 », le guide de publication de contenu dit 100 dans sa section sur les limites de fréquence et 50 de nouveau dans sa section carrousel. Lisez la valeur dans la réponse plutôt que de faire confiance à l'une ou l'autre page.

À quelle fréquence faut-il revérifier le quota dans une file de publication ?

Revérifiez avant chaque publication de la file, pas une seule fois au départ. La fenêtre est glissante, donc un lot de 20 posts qui n'a vérifié la capacité qu'au début peut dépasser le plafond vers le 14e post. Comparer quota_usage à config.quota_total à chaque envoi détecte cet écart avant qu'Instagram ne le fasse.

Un carrousel compte-t-il comme un post ou plusieurs dans quota_usage ?

Un carrousel compte comme un seul post quel que soit le nombre d'images qu'il contient, selon la phrase de Meta "Carousels count as a single post". Dix images publiées ensemble consomment la même unité de quota_usage qu'une seule image publiée seule. Cela rend les carrousels bien moins coûteux contre le plafond que de publier ces mêmes images une par une.

Que se passe-t-il si une app ignore la limite de publication ?

Meta recommande aux apps d'appliquer elles-mêmes la limite de fréquence, surtout quand elles permettent de programmer des posts à l'avance, car sauter la vérification ne fait que reporter l'échec au moment de la publication. Un compte au-dessus du quota reçoit une erreur HTTP 400, code 9, sous-code 2207042, et la capacité revient 24 heures après chaque publication, pas à une remise à zéro quotidienne. Un outil de programmation qui saute cette vérification préalable le découvre après s'être déjà engagé sur un horaire de publication qu'il ne peut plus tenir.

Une restriction pour spam équivaut-elle à atteindre le plafond de publication ?

Une restriction pour spam est un échec différent d'une limite de quota. Le code 4, sous-code 2207051, se déclenche quand une publication est "suspected to be spam", et réessayer le lendemain ne règle pas le problème comme le fait d'attendre le quota. Cette distinction compte pour une file d'attente, car les deux erreurs demandent des chemins de traitement séparés, l'un qui attend et l'autre qui s'arrête et signale le contenu.