La limite de légende Instagram que l'API de Meta applique vraiment

Quelle est la limite de légende Instagram sur l'API ?

Meta inscrit la limite de légende Instagram dans une seule phrase de la référence de l'endpoint de création de média : « Maximum 2200 characters, 30 hashtags, and 20 @ tags. » Cette phrase clôt la description du paramètre de requête caption sur POST /<IG_ID>/media, et c'est le seul endroit où Meta énonce les trois nombres ensemble.

La description complète du paramètre, citée telle que Meta la publie :

A caption for the image, video, or carousel. Can include hashtags (example: #crazywildebeest) and usernames of Instagram users (example: @natgeo). @Mentioned Instagram users receive a notification when the container is published. Maximum 2200 characters, 30 hashtags, and 20 @ tags.

Trois plafonds distincts vivent dans cette phrase unique, et ils échouent de trois façons différentes. Deux d'entre eux renvoient des erreurs documentées. Un ne le fait pas.

Où la légende se place-t-elle dans le flux de publication ?

La légende se place sur le conteneur, pas sur la publication. Le flux de publication de contenu d'Instagram comporte deux appels : POST /<IG_ID>/media crée le conteneur et POST /<IG_ID>/media_publish le publie. L'appel de publication prend creation_id et rien d'autre qui touche au texte.

curl -X POST "https://graph.facebook.com/<LATEST_API_VERSION>/<IG_USER_ID>/media" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d "image_url=<IMAGE_URL>" \
  -d "caption=<CAPTION>"

Une légende trop longue échoue donc à la création du conteneur, avant qu'aucun média ne soit publié et avant qu'aucun quota ne soit dépensé. C'est la version aimable de l'échec. Rien n'est passé en ligne, rien n'a été consommé, et le quota de publication glissant rapporté par content_publishing_limit reste intact, parce que ce compteur ne bouge que sur media_publish.

Les carrousels placent la légende à un endroit précis. Meta ajoute un avertissement au paramètre caption : « Not supported on images or videos in carousels. » La légende appartient au conteneur de carrousel créé avec media_type=CAROUSEL, et la poser sur un conteneur enfant ne fait rien. Le même avertissement apparaît sur location_id, les deux champs suivent donc la même règle.

Les stories sont plus étranges. La syntaxe de requête de Meta pour les conteneurs de story image et de story vidéo liste image_url ou video_url, media_type=STORIES, user_tags et access_token, et caption est absent des deux. Le tableau des paramètres décrit toujours caption de façon générique comme « A caption for the image, video, or carousel », ce qui ne mentionne les stories ni dans un sens ni dans l'autre. Meta ne l'autorise ni ne l'interdit par écrit.

Quelle erreur renvoie une légende trop longue ?

HTTP 400, code 36004, sous-code 2207010. La référence des codes d'erreur de Meta publie le message utilisateur avec ses emplacements de variables intacts :

The submitted image's caption was {submitted-caption-length} characters long. The maximum number of characters permitted for a caption is {maximum-caption-length}. Please submit media with a shorter caption.

La solution recommandée sur la même ligne redit le plafond : « The user exceeded the maximum amount of characters for a caption. Advise user to use a shorter caption. Maximum 2,200 characters, 30 hashtags, and 20 @ tags. »

Deux choses méritent d'être remarquées dans cette erreur. Le message interpole le vrai maximum à l'exécution au lieu de l'écrire en dur, ce qui veut dire que le nombre autoritaire vous parvient dans la chaîne d'erreur elle-même. Et la formulation dit « The submitted image's caption », alors que le même paramètre caption sert aux vidéos, aux reels et aux carrousels. Meta n'a pas généralisé la chaîne pour l'accorder au champ.

Le formatage des nombres diffère aussi entre les deux pages. La référence du paramètre écrit « 2200 characters ». La référence des codes d'erreur écrit « 2,200 characters ». Même chiffre, deux orthographes, signe fiable qu'aucune source unique ne génère les deux pages.

Que se passe-t-il quand vous dépassez 20 tags @ ?

HTTP 400, code 100, sous-code 2207040, avec le message « Cannot use more than {max-tag-count} tags per created media. » La solution recommandée de Meta fournit le nombre que le message laisse en variable : « The app user exceeded the maximum number (20) of @ tags. Advise user to use fewer @ tags. »

C'est le deuxième des trois plafonds, et celui que les gens atteignent sans le vouloir. Une légende qui crédite un photographe, un lieu, un styliste, trois collaborateurs et une marque en est déjà à huit mentions avant que le texte ne commence. Le plafond compte les tags @ dans le texte de la légende, mécanisme différent du paramètre user_tags qui place des noms d'utilisateur à des coordonnées x et y sur l'image, et différent encore de collaborators, que Meta plafonne séparément à « up to 3 instagram usernames ».

Les mentions ne sont pas cosmétiques non plus. Meta note que « @Mentioned Instagram users receive a notification when the container is published », ce qui fait du plafond de 20 tags un plafond de notifications autant qu'un plafond de texte.

Existe-t-il une erreur pour le 31e hashtag ?

Meta n'en publie aucune. Le plafond de 30 hashtags apparaît dans la description du paramètre caption et dans le texte de la solution recommandée sur la ligne d'erreur de longueur de légende, et nulle part dans le tableau des codes d'erreur Instagram il n'existe de ligne pour son dépassement. Il y a une ligne pour les légendes trop longues, une ligne pour trop de tags @, des lignes pour les comptages de carrousel, les tags produits, la taille d'image, le rapport d'aspect et le format vidéo. Les hashtags n'ont aucune ligne.

Ce silence laisse le comportement véritablement non documenté. Meta ne dit pas si un 31e hashtag fait rejeter le conteneur, se fait retirer, ou passe et se fait ignorer par la recherche. Le nombre 30 est publié. La conséquence de son dépassement ne l'est pas.

C'est le manque à contourner par la conception plutôt que par le test, parce que la réponse d'ingénierie honnête consiste à appliquer 30 dans votre propre éditeur et à ne jamais le découvrir. Cela se trouve aussi bien au-dessus du nombre qui sert à quelque chose, puisque la plage de hashtags qui bouge réellement l'engagement sur Instagram n'est nulle part près du plafond.

Comment la limite de l'API se compare-t-elle à ce que l'application autorise ?

Meta publie une seule limite de légende et c'est celle de l'API. La documentation développeur énonce 2 200 caractères, 30 hashtags et 20 tags @ pour le paramètre caption. La documentation d'aide de Meta pour l'application Instagram ne publie aucune limite de caractères de légende équivalente, aucun plafond de mentions dans l'app et aucun plafond de hashtags dans l'app que l'on puisse rattacher à une page Meta en ligne.

La comparaison que font la plupart des articles, selon laquelle l'API « correspond » à l'application à 2 200 caractères, est donc une comparaison entre un nombre documenté et un nombre qui ne l'est pas. Le chiffre de 2 200 est réel et sourcé. Son jumeau côté application est un folklore répété assez longtemps pour ressembler à une citation.

Le même motif se retrouve sur le champ voisin. Meta documente le plafond de 1 000 caractères du paramètre alt_text sur l'API de publication et ne publie aucune limite pour la boîte de texte alternatif dans l'application. Un côté du produit est spécifié, l'autre non.

Il existe une différence de comportement documentée, et elle favorise l'application. Les retours à la ligne et l'espacement sont gérés par l'éditeur de l'app, alors que l'API prend la chaîne que vous envoyez telle quelle, et c'est pourquoi les équipes qui construisent des légendes par programme finissent par résoudre elles-mêmes comment mettre des espaces dans une légende Instagram au lieu d'en hériter de l'interface.

Que doit vraiment vérifier un validateur de légende ?

Quatre vérifications couvrent tout ce que Meta documente, et elles tournent avant l'appel du conteneur plutôt qu'après l'erreur :

• Nombre de caractères à 2 200 ou en dessous, mesuré sur la chaîne finale après avoir défait tout encodage d'URL.
• Nombre de hashtags à 30 ou en dessous, appliqué localement puisque Meta ne renvoie aucune erreur pour cela.
• Nombre de mentions @ à 20 ou en dessous, conformément au plafond de 2207040.
• Légende attachée au conteneur de carrousel, jamais à un enfant de carrousel.

Traitez 36004 et 2207040 comme des erreurs d'appelant plutôt que comme des erreurs à réessayer. Ni l'une ni l'autre ne disparaîtra à une seconde tentative avec la même charge utile, et une boucle de relance contre une légende de 2 400 caractères brûlera des requêtes jusqu'à ce qu'autre chose casse.

Questions fréquentes

Quelle est la limite de légende exacte que Meta publie ?

« Maximum 2200 characters, 30 hashtags, and 20 @ tags », sur le paramètre caption de l'endpoint POST /<IG_ID>/media. La référence des codes d'erreur répète les mêmes chiffres sous la forme « 2,200 characters, 30 hashtags, and 20 @ tags ».

Quel code d'erreur signifie que la légende était trop longue ?

Le code 36004, sous-code 2207010, renvoyé en HTTP 400. Le message interpole à la fois la longueur soumise et le maximum, le vrai plafond revient donc dans l'erreur elle-même.

Peut-on poser une légende sur une image individuelle d'un carrousel ?

Non. Meta marque le paramètre caption « Not supported on images or videos in carousels ». La légende va sur le conteneur de carrousel créé avec media_type=CAROUSEL.

Les mentions @ dans une légende notifient-elles l'utilisateur ?

Oui. Meta énonce que « @Mentioned Instagram users receive a notification when the container is published », ce qui lie le plafond de 20 tags aux notifications plutôt qu'à la seule longueur du texte.

Que se passe-t-il si vous envoyez 31 hashtags ?

Meta ne le dit pas. Le plafond de 30 hashtags est publié dans la description du paramètre, et le tableau des codes d'erreur Instagram ne contient aucune ligne pour son dépassement, le comportement n'est donc pas documenté.

L'application Instagram applique-t-elle les mêmes 2 200 caractères ?

Meta publie ce nombre pour l'API seulement. Sa documentation d'aide ne porte aucune limite de caractères de légende équivalente pour l'éditeur de l'application, l'affirmation très répandue selon laquelle les deux correspondent ne peut donc pas être rattachée à Meta.

Que se passe-t-il quand une légende échoue à la création du conteneur ?

Le conteneur média n'est jamais créé, donc rien n'est publié et le quota de publication suivi par content_publishing_limit reste intact, puisque ce compteur ne bouge qu'à l'appel media_publish. L'échec survient avant que le média ne soit mis en ligne, ce qui le rend moins coûteux qu'un échec plus tard dans le flux. Corriger la légende et la renvoyer ne coûte rien de plus que la nouvelle tentative elle-même.

Peut-on ajouter une légende à un conteneur Stories Instagram ?

La syntaxe de requête que Meta documente pour les conteneurs de story liste image_url ou video_url, media_type=STORIES, user_tags et access_token, et caption est absent de cette liste. La description générique du paramètre caption couvre les images, les vidéos et les carrousels, mais ne dit rien sur les stories dans un sens ou dans l'autre. Meta n'autorise ni n'interdit par écrit une légende sur un conteneur de story.

La limite de 2 200 caractères s'applique-t-elle aussi aux vidéos et aux reels, pas seulement aux photos ?

Le paramètre caption se trouve sur le même point de terminaison POST /<IG_ID>/media quel que soit le type de média, donc les limites de 2 200 caractères, 30 hashtags et 20 tags s'appliquent aux vidéos et aux reels de la même façon qu'aux images. Le texte d'erreur continue d'appeler ça "the submitted image's caption" même quand le conteneur contient une vidéo, parce que Meta a écrit cette chaîne pour les images et ne l'a jamais mise à jour. Le libellé est incohérent, l'application de la limite ne l'est pas.

Les mentions @ dans une légende sont-elles les mêmes que les utilisateurs tagués sur l'image ?

Ce sont deux mécanismes distincts avec deux plafonds distincts. Les mentions @ vivent dans le texte de la légende et sont plafonnées à 20, tandis que user_tags place des noms d'utilisateur à des coordonnées x et y sur l'image et ne porte aucun plafond publié. Collaborators est un troisième mécanisme, séparé, plafonné à 3.