The Instagram Caption Limit Meta's API Actually Enforces

What is the Instagram caption limit on the API?

Meta writes the Instagram caption limit into a single sentence on the media creation endpoint reference: "Maximum 2200 characters, 30 hashtags, and 20 @ tags." That sentence closes the description of the caption query string parameter on POST /<IG_ID>/media, and it is the only place Meta states all three numbers together.

The full parameter description, quoted as Meta publishes it:

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.

Three separate ceilings live in that one sentence, and they fail in three different ways. Two of them return documented errors. One of them does not.

Where in the publishing flow does the caption go?

The caption goes on the container, not on the publish. Instagram's content publishing flow has two calls: POST /<IG_ID>/media creates the container and POST /<IG_ID>/media_publish publishes it. The publish call takes creation_id and nothing else that touches text.

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

A caption that is too long therefore fails at container creation, before any media is published and before quota is spent. That is the friendly version of the failure. Nothing has gone live, nothing has been consumed, and the rolling publishing quota reported by content_publishing_limit is untouched, because that counter only moves on media_publish.

Carousels put the caption in a specific place. Meta appends a warning to the caption parameter: "Not supported on images or videos in carousels." The caption belongs on the carousel container created with media_type=CAROUSEL, and setting it on a child container does nothing. The same warning appears on location_id, so both fields follow the same rule.

Stories are stranger. Meta's request syntax for image story containers and video story containers lists image_url or video_url, media_type=STORIES, user_tags and access_token, and caption is absent from both. The parameter table still describes caption generically as "A caption for the image, video, or carousel," which does not mention stories either way. Meta neither permits nor forbids it in writing.

What error does a long caption return?

HTTP 400, code 36004, subcode 2207010. Meta's error codes reference publishes the user message with the variable slots intact:

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.

The recommended solution on the same row restates the ceiling: "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."

Two things are worth noticing in that error. The message interpolates the real maximum at runtime rather than hardcoding it, which means the authoritative number reaches you in the error string itself. And the wording says "The submitted image's caption," even though the same caption parameter serves videos, reels and carousels. Meta has not generalised the string to match the field.

The number formatting differs between the two pages as well. The parameter reference writes "2200 characters." The error codes reference writes "2,200 characters." Same figure, two spellings, which is a reliable sign that no single source generates both pages.

What happens when you exceed 20 @ tags?

HTTP 400, code 100, subcode 2207040, with the message "Cannot use more than {max-tag-count} tags per created media." Meta's recommended solution supplies the number that the message leaves as a variable: "The app user exceeded the maximum number (20) of @ tags. Advise user to use fewer @ tags."

This is the second of the three ceilings, and it is the one people reach without meaning to. A caption that credits a photographer, a venue, a stylist, three collaborators and a brand is already at eight mentions before the copy starts. The cap counts @ tags inside the caption text, which is a different mechanism from the user_tags parameter that places usernames at x and y coordinates on the image, and different again from collaborators, which Meta caps separately at "up to 3 instagram usernames."

Mentions are not cosmetic, either. Meta notes that "@Mentioned Instagram users receive a notification when the container is published," which means the 20-tag cap is a notification cap as much as a text cap.

Is there an error for the 31st hashtag?

Meta publishes none. The hashtag cap of 30 appears in the caption parameter description and in the recommended solution text on the caption-length error row, and nowhere in the Instagram error codes table is there a row for exceeding it. There is a row for captions that are too long, a row for too many @ tags, rows for carousel counts, product tags, image size, aspect ratio and video format. Hashtags have no row.

That silence leaves the behaviour genuinely undocumented. Meta does not say whether a 31st hashtag rejects the container, gets stripped, or publishes and is ignored by search. The number 30 is published. The consequence of passing it is not.

This is the gap to plan around rather than test around, because the honest engineering answer is to enforce 30 in your own composer and never find out. It also happens to be far above the count that does any good, since the hashtag range that actually moves engagement on Instagram sits nowhere near the ceiling.

How does the API limit compare to what the app allows?

Meta publishes one caption limit and it is the API's. The developer documentation states 2,200 characters, 30 hashtags and 20 @ tags for the caption parameter. Meta's help documentation for the Instagram app publishes no equivalent caption character limit, no in-app mention cap and no in-app hashtag cap that can be cited back to a live Meta page.

So the comparison most articles make, that the API "matches" the app at 2,200 characters, is a comparison between a documented number and an undocumented one. The 2,200 figure is real and sourced. Its in-app twin is folklore that has been repeated long enough to look like a citation.

The same pattern shows up on the neighbouring field. Meta documents the alt_text parameter's 1,000-character ceiling on the publishing API and publishes no limit for the alt text box inside the app. One side of the product is specified, the other side is not.

There is one behaviour difference that is documented, and it favours the app. Line breaks and spacing are handled by the composer in the app, while the API takes whatever string you send, which is why teams building captions programmatically end up solving how to put spaces in an Instagram caption themselves rather than inheriting it from the interface.

What should a caption validator actually check?

Four checks cover everything Meta documents, and they run before the container call rather than after the error:

• Character count at or below 2,200, measured on the final string after any URL encoding is undone.
• Hashtag count at or below 30, enforced locally because Meta returns no error for it.
• At-mention count at or below 20, matching the 2207040 cap.
• Caption attached to the carousel container, never to a carousel child.

Handle 36004 and 2207040 as caller errors rather than retryable ones. Neither will clear on a second attempt with the same payload, and a retry loop against a caption that is 2,400 characters long will burn requests until something else breaks.

Frequently asked questions

What is the exact caption limit Meta publishes?

"Maximum 2200 characters, 30 hashtags, and 20 @ tags," on the caption parameter of the POST /<IG_ID>/media endpoint. The error codes reference repeats the same figures as "2,200 characters, 30 hashtags, and 20 @ tags."

Which error code means the caption was too long?

Code 36004, subcode 2207010, returned as HTTP 400. The message interpolates both the submitted length and the maximum, so the real ceiling comes back in the error itself.

Can you set a caption on an individual carousel image?

No. Meta marks the caption parameter "Not supported on images or videos in carousels." The caption goes on the carousel container created with media_type=CAROUSEL.

Do @ mentions in a caption notify the user?

Yes. Meta states that "@Mentioned Instagram users receive a notification when the container is published," which ties the 20-tag cap to notifications rather than to text length alone.

What happens if you send 31 hashtags?

Meta does not say. The 30-hashtag cap is published in the parameter description, and the Instagram error codes table contains no row for exceeding it, so the behaviour is undocumented.

Does the Instagram app enforce the same 2,200 characters?

Meta publishes that number for the API only. Its help documentation carries no equivalent caption character limit for the app composer, so the widely repeated claim that both match cannot be sourced back to Meta.

What happens when a caption fails at container creation?

The media container never gets created, so nothing publishes and the rolling publishing quota tracked by content_publishing_limit stays untouched, because that counter only moves on media_publish. The failure lands before any media goes live, which makes it cheaper than a failure later in the flow. Fixing the caption and resubmitting costs nothing beyond the retry itself.

Can you add a caption to an Instagram Stories container?

Meta's documented request syntax for story containers lists image_url or video_url, media_type=STORIES, user_tags and access_token, with caption absent from that list. The generic caption parameter description covers images, videos and carousels but says nothing about stories either way. Meta neither permits nor forbids a caption on a story container in writing.

Does the 2,200-character limit apply to videos and reels, not just photos?

The caption parameter sits on the same POST /<IG_ID>/media endpoint regardless of media type, so the 2,200-character, 30-hashtag and 20-tag ceilings apply the same way to videos and reels as to images. The error message still calls it "the submitted image's caption" even when the container holds a video, because Meta wrote that string for images and never updated it. The wording is inconsistent. The enforcement is not.

Are @ mentions in a caption the same as tagged users on the image?

They are two separate mechanisms with two separate caps. @ mentions live inside the caption text and are capped at 20, while user_tags places usernames at x and y coordinates on the image and carries no published cap at all. Collaborators is a third, separate mechanism capped at 3.