Instagram Graph API publishing: limits and errors

You publish to Instagram through the API in two calls: POST /{ig-user-id}/media creates a container that holds your picture or video and caption, and POST /{ig-user-id}/media_publish with that container's creation_id makes it a post. For video the two calls are not enough on their own, because Instagram processes the file in between and the container must report status_code: FINISHED before the second call works. It only works for professional accounts (Business or Creator), never for personal ones, and the media has to sit at a public URL when Instagram fetches it.

That is the whole shape. What costs people days is everything around it: a daily cap that Meta's own pages state two different ways, JPEG-only pictures, a status field a naive script never reads, and error codes that mean three different things depending on the subcode. This guide comes from the code Preflight runs every day to publish to Instagram, so it also says where publishing fails in practice. Facts were checked against Meta's documentation on 8 October 2026.

What you need before the first call

An account Instagram can publish to. The API publishes to Instagram professional accounts: Business or Creator. A personal account cannot be published to by any tool; switching it to Creator or Business is free and done in the Instagram app.

One of two ways to connect it. Meta now offers two integrations, and they differ in host, token and permission names:

If the user holds a Business Manager role on the Page, Facebook Login also asks for ads_management or ads_read. With Facebook Login, the person connecting needs the MANAGE or CREATE_CONTENT task on the Page, and a Page that requires Page Publishing Authorization or two-factor authentication blocks publishing until that is done.

Access level. Both integrations work at Standard access for accounts that belong to your own app's team. For anyone else's account you need Advanced access, which means Meta's app review with a screencast of the publishing flow.

A token that lives. An Instagram Login token is long-lived for 60 days and can be refreshed (graph.instagram.com/refresh_access_token) only while it is still valid; once it lapses, the user has to authorise again. A Facebook Page token obtained from a long-lived user token does not expire. Preflight refreshes the first kind before it runs out and treats a failed refresh as a reason to ask the user to reconnect, not as a transient error.

The two steps

Step 1: create the container. The parameters depend on what you publish:

• Feed picture: image_url, optional caption, optional alt_text (up to 1,000 characters, pictures only).
• Reel: media_type=REELS, video_url, optional caption, share_to_feed, cover_url or thumb_offset, trial_params.
• Story: media_type=STORIES with image_url or video_url. No caption.
• Carousel: one container per item with is_carousel_item=true (no caption on the children), then a parent with media_type=CAROUSEL, children as a comma-separated list of up to 10 container IDs, and the caption.

video_url takes a public URL. Large files can be sent with upload_type=resumable to rupload.facebook.com, which Meta documents for Facebook Login apps only.

Step 2: wait. Creating a container returns an ID immediately, and that ID says nothing about whether the media was fetched, decoded and accepted. Read GET /{container-id}?fields=status_code,status until it says:

Meta recommends polling once a minute for at most five minutes. Pictures are usually ready within seconds; a long reel can take longer than the five minutes, so a worker that insists on finishing in one run will either time out or hold a slot. Preflight waits about 30 seconds for a video inside the publishing job and then parks the container as pending; a separate job looks once a minute and publishes it the moment Instagram reports FINISHED.

Step 3: publish. media_publish with the creation_id returns the media ID.

Why a tool that does not wait reports success and nothing appears. A script that calls media_publish straight after creating a video container gets an error (code 9007, subcode 2207027, "media not ready") at best. A script that swallows the error, or counts the successful container creation as the result, tells the user "published" for a post that was never made. The container call succeeding means only that Instagram accepted the request. Success is a media ID from media_publish.

What each post type accepts

Three details trip people up. A phone photo is 3:4, which is 0.75, below the 0.8 floor of 4:5, so it is refused; crop it first. A PNG or WebP is refused outright: the API takes JPEG only. And the published object does not say what it was: a Reel comes back with media_type: VIDEO and a story with IMAGE or VIDEO; read media_product_type to tell them apart. For every network side by side, see the limits table.

The daily cap

Meta's documentation gives two numbers for how many posts an account may publish through the API per rolling 24 hours:

• The content publishing guide says 100 in its rate-limit section, and 50 in its carousel section.
• The media_publish reference and the content_publishing_limit reference both say 50.

Treat 50 as the working number, since it is the one the endpoint itself reports (the 100 may reflect an older or planned figure; Meta does not reconcile them). The cap is counted when you call media_publish, not when you create containers, and a carousel counts as one. The window is a moving 24 hours, so a slot frees 24 hours after each individual publish, not at midnight. Creating containers has its own, separate ceiling of 400 per rolling 24 hours.

You do not have to guess. GET /{ig-user-id}/content_publishing_limit?fields=config,quota_usage returns quota_usage (publishes in the last 24 hours, or since a since Unix timestamp no older than 24 hours) and config.quota_total and config.quota_duration (currently 50 and 86,400 seconds). Without fields, only the usage comes back. Meta's own advice is that apps enforce the limit themselves, especially for scheduled posts.

When the limit is hit, media_publish fails with code 9, subcode 2207042. It is not permanent. Preflight treats it as a wait: it retries after three hours, up to 12 attempts, which covers a full day of window rolling, instead of failing the post after five quick retries inside the same window. If you build your own, queue by the quota_usage you read and keep a margin, because other tools publishing to the same account share the same count.

Errors you will meet

Meta's error-code reference lists these for content publishing (all returned as HTTP 400). The third column is what to do, and where Preflight acts on its own, it says so.

When status_code is ERROR, the status field holds a subcode you can look up in Meta's error codes page. Preflight splits those into two groups: a reason Meta names is the file's fault, so it is permanent and shown to the user; an unnamed "unknown" failure is usually a dropped transcode on Meta's side, which is retried.

What the API will not do

• Schedule natively. None of the Instagram endpoints takes a publish time. scheduled_publish_time is a Facebook Page feature; Meta's publishing guide and media_publish reference mention no scheduling at all. Every Instagram scheduler, Preflight included, keeps the post itself and calls the API at the chosen minute. Store the file and the caption, not the container, which expires after 24 hours.
• Tag people, places and products from every app. user_tags (public accounts, with coordinates on pictures), location_id (a Page ID with location data) and product_tags (Shop catalogue, extra permissions) exist in the reference. collaborators takes up to three usernames. Preflight sends collaborators, alt text, trial reels, the reel cover and share-to-feed, and does not send user tags, locations, product tags, the AI-generated label or audio names.
• Music. There is no way to attach a track from Instagram's library; audio_name only renames the audio of your own Reel, once.
• Edit a caption after publishing. The publishing endpoints list no update. Preflight marks Instagram as not editable.
• Delete. The publishing references say deletion is unsupported. In practice Preflight's code issues DELETE /{media-id} for accounts connected through a Facebook Page, which needs instagram_manage_contents, and tells users that accounts connected directly with Instagram Login cannot delete through the API. We could not find that call in Meta's current reference pages, so treat it as observed behaviour, not documented behaviour, and test it before you promise it.
• Personal accounts. Not at all, by any app.

How Preflight handles it

Everything above runs before and around the two calls. Before upload, Preflight checks the caption length, 30 hashtags and 20 mentions, the 4:5 to 1.91:1 ratio, Reel length and frame rate, story length and size, and the 10-item carousel. A picture that is not a JPEG or is over 8 MB is converted once: turned upright, fitted to 1,440 pixels wide, transparency put on white, and the JPEG handed to Instagram while the original stays in your library. Containers are polled, videos are parked and resumed, transient errors are retried with the delay Meta asks for, token failures are flagged for reconnecting, and the daily cap becomes a three-hour wait. Preflight does not call content_publishing_limit ahead of time; it reacts to code 9, subcode 2207042, which is the one answer the API cannot get wrong.

These checks run on every plan, the free one included, and the same rules are available through the API for tools that post on your behalf. To connect an account and see what goes out, start at the Instagram integration page; the full rule list is on Instagram limits, and how scheduling works in the product is in scheduling Instagram posts.

Checked against Meta's Instagram content publishing guide, the IG User media reference and the content_publishing_limit reference on 8 October 2026, and against Preflight's own publishing code.