Lire le status_code du conteneur Instagram avant de publier

Qu'est-ce que le status_code du conteneur Instagram ?

Publier sur Instagram par l'API se fait en deux appels, et le status_code du conteneur Instagram est le champ qui vous dit si le second appel fonctionnera. Le premier appel crée un conteneur avec POST /<IG_ID>/media. Le second le publie avec POST /<IG_ID>/media_publish. Entre les deux se glisse un transcodage asynchrone que vous ne voyez pas, et la référence de Meta le dit sans détour : « Video uploads are asynchronous, so receiving a container ID does not guarantee that the upload was successful. »

Le champ vit sur le nœud IG Container. Meta le définit comme « The container's publishing status » et vous le lisez avec une seule requête :

curl -X GET \
  'https://graph.instagram.com/17889615691921648?fields=status_code&access_token=IGQVJ...'

{
  "status_code": "FINISHED",
  "id": "17889615691921648"
}

Que signifie chaque valeur de status_code ?

Meta documente cinq valeurs et aucune autre. Les définitions ci-dessous sont celles imprimées dans la référence IG Container et reprises mot pour mot dans le guide Content Publishing.

Deux de ces cinq valeurs sont terminales, au sens où aucune attente ne les fera changer. ERROR et EXPIRED signifient toutes deux que le conteneur que vous tenez est mort. FINISHED est la seule valeur qui veut dire allez-y.

Il y a un second champ à demander sur le même appel. copyright_check_status renvoie matches_found sous forme de booléen et son propre status réglé sur completed, error, in_progress ou not_started. Un reel peut atteindre FINISHED sur status_code alors que la vérification des droits d'auteur est encore in_progress, ce qui explique en partie qu'une publication qui semblait prête revienne quand même mécontente.

À quelle fréquence Meta dit-il de sonder le conteneur ?

Meta donne une seule phrase de conseil : « We recommend querying a container's status once per minute, for no more than 5 minutes. » Cela fait cinq requêtes, au total, par conteneur.

Le chiffre mérite qu'on le fixe un moment, parce que la même documentation fixe la durée de vie du conteneur à 24 heures. Cinq minutes de sondage couvrent environ 0,35 pour cent de la fenêtre pendant laquelle le conteneur est valide. Meta ne dit jamais ce qu'un client doit faire d'un conteneur encore IN_PROGRESS à la sixième minute. La documentation s'arrête, tout simplement.

En pratique, un long reel qui transcode encore à la cinquième minute est en train de transcoder, et le conteneur reste bon pour 23 heures et 55 minutes de plus. Le plafond de cinq minutes se lit comme un conseil sur la force à mettre à cogner l'endpoint, pas comme une affirmation sur le moment où un conteneur devient sans espoir. Le prendre pour la seconde chose vous fait jeter des conteneurs qui auraient abouti.

Combien de temps un conteneur Instagram dure-t-il avant d'expirer ?

Les conteneurs expirent au bout de 24 heures. La référence IG User Media l'indique dans sa liste de limitations générales, et la définition d'EXPIRED le redit dans l'autre sens : le conteneur « was not published within 24 hours. »

La même liste ajoute un second chiffre qui compte quand vous mettez des posts en file en masse : « An Instagram account can only create 400 containers within a rolling 24 hour period. » C'est un budget de conteneurs, pas un budget de publication, et il compte chaque conteneur que vous créez, que vous le publiiez ou non. Une boucle de reprise qui reconstruit un conteneur à chaque échec le consume vite.

Le budget de publication est un chiffre séparé, et là le guide de Meta se contredit lui-même sur une seule page. La section Rate Limit du guide Content Publishing dit « Instagram accounts are limited to 100 API-published posts within a 24-hour moving period. » La section Limitations des carrousels, plus bas sur la même page, dit « Accounts are limited to 50 published posts within a 24-hour period. » Les deux phrases sont en ligne. Les deux ajoutent qu'un carrousel compte pour un post. Quiconque développe contre cela devrait interroger GET /<IG_ID>/content_publishing_limit et s'y fier plutôt qu'à l'un ou l'autre paragraphe, l'approche que nous prenons dans l'article sur la limite de publication de contenu d'Instagram et sur le plafond de 100 posts par 24 heures.

Que faire quand status_code renvoie ERROR ?

Demandez le champ status sur le même conteneur. La définition que Meta donne de ce champ est la partie utile : « Publishing status. If status_code is ERROR, this value will be an error subcode. »

Donc status_code vous dit que quelque chose a cassé et status vous dit quoi. Les sous-codes qui reviennent le plus souvent sur un conteneur en échec sortent du tableau des codes d'erreur Instagram de Meta :

Le dernier est le plus honnête. Le correctif que Meta recommande pour 2207053 est « Generate a new container and use it to try again », et Meta note que le sous-code « should only affect video uploads. »

Quatre de ces sept sont corrigibles avant même de créer un conteneur, en validant le fichier contre les spécifications publiées. Les règles de légende sont traitées dans la note sur la limite de 2 200 caractères de légende, et les règles vidéo dans le détail de ce que l'API Reels d'Instagram accepte.

Que faire quand status_code renvoie EXPIRED ?

Tout recommencer. Il n'existe aucun endpoint qui ressuscite un conteneur expiré, aucun paramètre de prolongation, et aucune opération de mise à jour sur le nœud. La référence IG Container dit « This operation is not supported » sous Creating, Updating et Deleting à la fois. De votre côté, un conteneur est en lecture seule.

Le tableau d'erreurs de Meta confirme le remède dans la colonne de solution recommandée du sous-code 2207020, dont le message est The media you are trying to access has expired. Please try to upload again. Le correctif donné est « Generate a new container ID and use it to try again. »

Un sous-code voisin est facile à confondre avec l'expiration et n'est pas la même chose. Le sous-code 2207008 renvoie The media builder with creation id = {creation-id} does not exist or has been expired. Meta appelle cela une « Temporary error publishing a container » et vous conseille de « Try again 1-2 times in the next 30 seconds to 2 minutes. If unsuccessful, generate a new container ID. » Donc le message dit expiré, le conseil dit réessayez. Réessayez avant de reconstruire.

Pourquoi media_publish échoue-t-il quand status_code dit FINISHED ?

Parce que FINISHED décrit le conteneur, pas le compte. Trois échecs survivent à un FINISHED propre.

Le sous-code 2207027 renvoie The media is not ready for publishing, please wait for a moment, et le correctif de Meta est de vérifier le statut du conteneur et de publier quand il affiche FINISHED, ce qui est circulaire quand FINISHED est précisément ce que vous venez de lire. Traitez-le comme une course et réessayez.

Le sous-code 2207042 renvoie You reached maximum number of posts that is allowed to be published by Content Publishing API. Le conteneur va bien ; c'est l'allocation quotidienne qui est partie. Le conseil de Meta est d'« Advise the app's user to try again the following day. »

Le sous-code 2207050 renvoie The Instagram account is restricted. Meta explique que le compte « is inactive, checkpointed, or restricted » et que la seule issue passe par l'application Instagram, pas par l'API. C'est le même mur que derrière la plupart des raisons que les gens trouvent quand ils demandent pourquoi ils ne peuvent pas publier sur Instagram.

Questions fréquentes

Combien de valeurs status_code peut-il renvoyer ?

Cinq. IN_PROGRESS, FINISHED, PUBLISHED, ERROR et EXPIRED. La référence IG Container de Meta liste exactement celles-là et aucune autre.

Un conteneur photo a-t-il seulement besoin d'être sondé ?

La section de dépannage de Meta articule le sondage de statut autour de la vidéo, puisque les conteneurs d'image se résolvent dès l'appel de création. Demander status_code sur un conteneur d'image fonctionne quand même et renvoie quand même l'une des cinq valeurs.

Combien de temps attendre entre deux sondages ?

Une fois par minute. La formulation exacte de Meta est « We recommend querying a container's status once per minute, for no more than 5 minutes. »

Que devient un conteneur que vous ne publiez jamais ?

Il expire 24 heures après sa création et compte dans la limite de 400 conteneurs par période glissante de 24 heures. Les conteneurs non publiés ne comptent pas dans la limite de publication.

Peut-on supprimer un conteneur pour libérer du quota ?

Non. Le nœud IG Container liste Deleting comme « This operation is not supported. » Les conteneurs se nettoient tout seuls quand ils expirent.

Quel champ vous dit pourquoi la publication a échoué ?

Le champ status, pas status_code. Meta documente que lorsque status_code vaut ERROR, la valeur de status est un sous-code d'erreur que vous allez ensuite chercher dans le tableau des codes d'erreur Instagram.

Combien de sous-codes ERROR peut-on éviter avant de créer un conteneur ?

Quatre des sept sous-codes du tableau de Meta sont évitables avant même qu'un conteneur existe. Vérifier le fichier, ses dimensions et la longueur de la légende par rapport aux spécifications publiées par Meta permet de repérer un mauvais format vidéo, un rapport d'aspect hors limites, une image trop lourde ou une légende trop longue avant l'envoi, puisque ces conditions sont déjà connues avant la création du conteneur.

Un conteneur peut-il atteindre FINISHED avant la fin de la vérification des droits d'auteur ?

Oui. Un reel peut atteindre FINISHED sur status_code alors que copyright_check_status est encore in_progress, si bien que le conteneur paraît prêt avant même que la vérification des droits d'auteur soit réellement terminée. Ce champ renvoie matches_found sous forme de booléen ainsi qu'un statut completed, error, in_progress ou not_started, qu'il vaut mieux demander en même temps que status_code avant de publier.

Pourquoi la documentation de Meta se contredit-elle sur la limite de publication ?

La section Rate Limit du guide Content Publishing plafonne les comptes à 100 publications via l'API sur une période glissante de 24 heures, tandis que la section Limitations sur les carrousels, plus bas sur la même page, annonce une limite de 50 publications sur 24 heures. Les deux phrases sont toujours en ligne. Interroger GET /<IG_ID>/content_publishing_limit et se fier à cette réponse plutôt qu'à l'un ou l'autre paragraphe évite de deviner.

Le sous-code 2207008 signifie-t-il que le conteneur a expiré ?

Non, même si son message dit "has been expired". Meta classe 2207008 comme une erreur temporaire et recommande de réessayer une ou deux fois dans les 30 secondes à 2 minutes suivantes avant de créer un nouveau conteneur. Un vrai statut EXPIRED, lui, n'offre aucune possibilité de nouvelle tentative.