Welches Instagram-Caption-Limit Metas API tatsächlich erzwingt

Wie lautet das Instagram-Caption-Limit in der API?

Meta schreibt das Instagram-Caption-Limit in einen einzigen Satz in der Referenz zum Endpunkt der Medienerstellung: „Maximum 2200 characters, 30 hashtags, and 20 @ tags.“ Dieser Satz beendet die Beschreibung des Query-String-Parameters caption an POST /<IG_ID>/media, und es ist die einzige Stelle, an der Meta alle drei Zahlen zusammen nennt.

Die vollständige Parameterbeschreibung, zitiert, wie Meta sie veröffentlicht:

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.

Drei getrennte Obergrenzen leben in diesem einen Satz, und sie scheitern auf drei verschiedene Weisen. Zwei davon liefern dokumentierte Fehler. Eine nicht.

Wo im Veröffentlichungsablauf sitzt die Caption?

Die Caption sitzt am Container, nicht an der Veröffentlichung. Instagrams Ablauf zur Inhaltsveröffentlichung hat zwei Aufrufe: POST /<IG_ID>/media erstellt den Container und POST /<IG_ID>/media_publish veröffentlicht ihn. Der Veröffentlichungsaufruf nimmt creation_id und nichts weiter, das Text berührt.

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>"

Eine zu lange Caption scheitert damit bei der Container-Erstellung, bevor irgendein Medium veröffentlicht und bevor Quote verbraucht wird. Das ist die freundliche Variante des Fehlschlags. Nichts ist live gegangen, nichts wurde verbraucht, und die rollierende Veröffentlichungsquote, die content_publishing_limit meldet, bleibt unberührt, weil dieser Zähler sich nur bei media_publish bewegt.

Bei Karussells gehört die Caption an eine bestimmte Stelle. Meta hängt an den Parameter caption eine Warnung: „Not supported on images or videos in carousels.“ Die Caption gehört an den Karussell-Container, der mit media_type=CAROUSEL erstellt wird, und sie an einem Kind-Container zu setzen bewirkt nichts. Dieselbe Warnung erscheint an location_id, beide Felder folgen also derselben Regel.

Stories sind seltsamer. Metas Anfragesyntax für Bild-Story-Container und Video-Story-Container listet image_url oder video_url, media_type=STORIES, user_tags und access_token, und caption fehlt in beiden. Die Parametertabelle beschreibt caption weiterhin allgemein als „A caption for the image, video, or carousel“, was Stories in keine Richtung erwähnt. Meta erlaubt es schriftlich weder noch verbietet es das.

Welchen Fehler liefert eine zu lange Caption?

HTTP 400, Code 36004, Subcode 2207010. Metas Referenz zu Fehlercodes veröffentlicht die Nutzermeldung mit den Variablenplätzen intakt:

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.

Die empfohlene Lösung in derselben Zeile wiederholt die Obergrenze: „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.“

Zwei Dinge sind an diesem Fehler bemerkenswert. Die Meldung setzt das echte Maximum zur Laufzeit ein, statt es fest zu verdrahten, was heißt, dass die maßgebliche Zahl Sie in der Fehlermeldung selbst erreicht. Und der Wortlaut sagt „The submitted image's caption“, obwohl derselbe Parameter caption auch Videos, Reels und Karussells bedient. Meta hat die Zeichenfolge nicht an das Feld angepasst.

Auch die Zahlenschreibweise unterscheidet sich zwischen den beiden Seiten. Die Parameterreferenz schreibt „2200 characters“. Die Referenz zu Fehlercodes schreibt „2,200 characters“. Dieselbe Zahl, zwei Schreibweisen, ein verlässliches Zeichen, dass keine gemeinsame Quelle beide Seiten erzeugt.

Was passiert, wenn Sie 20 @-Tags überschreiten?

HTTP 400, Code 100, Subcode 2207040, mit der Meldung „Cannot use more than {max-tag-count} tags per created media.“ Metas empfohlene Lösung liefert die Zahl, die die Meldung als Variable offenlässt: „The app user exceeded the maximum number (20) of @ tags. Advise user to use fewer @ tags.“

Das ist die zweite der drei Obergrenzen, und es ist die, die Leute ungewollt erreichen. Eine Caption, die einen Fotografen, eine Location, eine Stylistin, drei Mitwirkende und eine Marke nennt, liegt bei acht Erwähnungen, bevor der Text überhaupt beginnt. Die Grenze zählt @-Tags im Caption-Text, was ein anderer Mechanismus ist als der Parameter user_tags, der Nutzernamen an x- und y-Koordinaten auf dem Bild platziert, und wieder ein anderer als collaborators, das Meta separat auf „up to 3 instagram usernames“ deckelt.

Erwähnungen sind auch nicht kosmetisch. Meta merkt an, dass „@Mentioned Instagram users receive a notification when the container is published“, was heißt, dass die Grenze von 20 Tags ebenso eine Benachrichtigungsgrenze wie eine Textgrenze ist.

Gibt es einen Fehler für den 31. Hashtag?

Meta veröffentlicht keinen. Die Hashtag-Grenze von 30 erscheint in der Beschreibung des Parameters caption und im Text der empfohlenen Lösung in der Fehlerzeile zur Caption-Länge, und nirgends in Instagrams Fehlercode-Tabelle gibt es eine Zeile für ihr Überschreiten. Es gibt eine Zeile für zu lange Captions, eine Zeile für zu viele @-Tags, Zeilen für Karussell-Anzahlen, Produkt-Tags, Bildgröße, Seitenverhältnis und Videoformat. Hashtags haben keine Zeile.

Dieses Schweigen lässt das Verhalten wirklich undokumentiert. Meta sagt nicht, ob ein 31. Hashtag den Container ablehnt, entfernt wird oder veröffentlicht und von der Suche ignoriert wird. Die Zahl 30 ist veröffentlicht. Die Folge ihres Überschreitens nicht.

Das ist die Lücke, um die herum man planen sollte statt um sie herum zu testen, denn die ehrliche technische Antwort ist, 30 im eigenen Composer zu erzwingen und es nie herauszufinden. Es liegt ohnehin weit über der Zahl, die überhaupt etwas bringt, denn die Hashtag-Spanne, die auf Instagram tatsächlich das Engagement bewegt, liegt nirgends in der Nähe der Obergrenze.

Wie verhält sich das API-Limit zu dem, was die App erlaubt?

Meta veröffentlicht ein Caption-Limit, und das ist das der API. Die Entwicklerdokumentation nennt 2.200 Zeichen, 30 Hashtags und 20 @-Tags für den Parameter caption. Metas Hilfedokumentation für die Instagram-App veröffentlicht kein entsprechendes Zeichenlimit für Captions, keine In-App-Grenze für Erwähnungen und keine In-App-Grenze für Hashtags, die sich auf eine aktive Meta-Seite zurückführen ließe.

Der Vergleich, den die meisten Artikel anstellen, dass die API dem Wert der App bei 2.200 Zeichen „entspricht“, ist damit ein Vergleich zwischen einer dokumentierten und einer undokumentierten Zahl. Die Zahl 2.200 ist echt und belegt. Ihr In-App-Zwilling ist Folklore, die lange genug wiederholt wurde, um wie ein Beleg auszusehen.

Dasselbe Muster zeigt sich am Nachbarfeld. Meta dokumentiert die Obergrenze von 1.000 Zeichen am Parameter alt_text in der Veröffentlichungs-API und veröffentlicht kein Limit für das Alt-Text-Feld in der App. Eine Seite des Produkts ist spezifiziert, die andere nicht.

Es gibt einen dokumentierten Verhaltensunterschied, und er spricht für die App. Zeilenumbrüche und Abstände übernimmt der Composer in der App, während die API die Zeichenfolge nimmt, die Sie senden, weshalb Teams, die Captions programmatisch bauen, das Setzen von Abständen in einer Instagram-Caption selbst lösen müssen, statt es von der Oberfläche zu erben.

Was sollte ein Caption-Validator tatsächlich prüfen?

Vier Prüfungen decken alles ab, was Meta dokumentiert, und sie laufen vor dem Container-Aufruf statt nach dem Fehler:

• Zeichenzahl bei höchstens 2.200, gemessen an der endgültigen Zeichenfolge, nachdem jede URL-Kodierung zurückgenommen wurde.
• Hashtag-Zahl bei höchstens 30, lokal erzwungen, weil Meta dafür keinen Fehler liefert.
• Zahl der @-Erwähnungen bei höchstens 20, passend zur Grenze von 2207040.
• Caption am Karussell-Container, niemals an einem Karussell-Kind.

Behandeln Sie 36004 und 2207040 als Aufruferfehler und nicht als wiederholbar. Keiner klärt sich bei einem zweiten Versuch mit derselben Nutzlast, und eine Wiederholungsschleife gegen eine 2.400 Zeichen lange Caption verbrennt Anfragen, bis etwas anderes bricht.

Häufig gestellte Fragen

Welches Caption-Limit veröffentlicht Meta genau?

„Maximum 2200 characters, 30 hashtags, and 20 @ tags“, am Parameter caption des Endpunkts POST /<IG_ID>/media. Die Referenz zu Fehlercodes wiederholt dieselben Zahlen als „2,200 characters, 30 hashtags, and 20 @ tags“.

Welcher Fehlercode bedeutet, dass die Caption zu lang war?

Code 36004, Subcode 2207010, geliefert als HTTP 400. Die Meldung setzt sowohl die eingereichte Länge als auch das Maximum ein, die echte Obergrenze kommt also im Fehler selbst zurück.

Kann man eine Caption an einem einzelnen Karussellbild setzen?

Nein. Meta markiert den Parameter caption mit „Not supported on images or videos in carousels“. Die Caption gehört an den Karussell-Container, der mit media_type=CAROUSEL erstellt wird.

Benachrichtigen @-Erwähnungen in einer Caption den Nutzer?

Ja. Meta hält fest, dass „@Mentioned Instagram users receive a notification when the container is published“, was die Grenze von 20 Tags an Benachrichtigungen bindet und nicht nur an die Textlänge.

Was passiert, wenn Sie 31 Hashtags senden?

Meta sagt es nicht. Die Grenze von 30 Hashtags ist in der Parameterbeschreibung veröffentlicht, und Instagrams Fehlercode-Tabelle enthält keine Zeile für ihr Überschreiten, das Verhalten ist also undokumentiert.

Erzwingt die Instagram-App dieselben 2.200 Zeichen?

Meta veröffentlicht diese Zahl nur für die API. Seine Hilfedokumentation führt kein entsprechendes Zeichenlimit für Captions im App-Composer, die weit verbreitete Behauptung, beide seien gleich, lässt sich also nicht auf Meta zurückführen.

Was passiert, wenn eine Caption bei der Container-Erstellung fehlschlägt?

Der Medien-Container wird nie erstellt, sodass nichts veröffentlicht wird und das von content_publishing_limit erfasste Veröffentlichungskontingent unangetastet bleibt, weil sich dieser Zähler nur bei media_publish bewegt. Der Fehler tritt auf, bevor irgendein Medium live geht, was ihn günstiger macht als ein Fehler später im Ablauf. Die Caption zu korrigieren und erneut zu senden kostet nichts außer dem erneuten Versuch selbst.

Kann man einem Instagram-Stories-Container eine Caption geben?

Metas dokumentierte Anfragesyntax für Story-Container listet image_url oder video_url, media_type=STORIES, user_tags und access_token auf, caption fehlt in dieser Liste. Die allgemeine Beschreibung des caption-Parameters deckt Bilder, Videos und Karussells ab, sagt aber nichts über Stories in die eine oder andere Richtung. Meta erlaubt oder verbietet eine Caption auf einem Story-Container schriftlich nicht.

Gilt das 2.200-Zeichen-Limit auch für Videos und Reels, nicht nur für Fotos?

Der caption-Parameter sitzt unabhängig vom Medientyp auf demselben Endpunkt POST /<IG_ID>/media, also gelten die Grenzen von 2.200 Zeichen, 30 Hashtags und 20 Tags für Videos und Reels genauso wie für Bilder. Der Fehlertext nennt es weiterhin "the submitted image's caption", selbst wenn der Container ein Video enthält, weil Meta diese Zeichenkette für Bilder geschrieben und nie aktualisiert hat. Der Wortlaut ist inkonsistent, die Durchsetzung nicht.

Sind @-Erwähnungen in einer Caption dasselbe wie markierte Nutzer im Bild?

Es sind zwei getrennte Mechanismen mit zwei getrennten Obergrenzen. @-Erwähnungen stehen im Caption-Text und sind bei 20 gedeckelt, während user_tags Nutzernamen an x- und y-Koordinaten im Bild platziert und keine veröffentlichte Obergrenze trägt. Collaborators ist ein dritter, separater Mechanismus, der bei 3 gedeckelt ist.