Reading the Instagram Container status_code Before You Publish

What is the Instagram container status_code?

Publishing to Instagram through the API happens in two calls, and the Instagram container status_code is the field that tells you whether the second call will work. The first call creates a container with POST /<IG_ID>/media. The second publishes it with POST /<IG_ID>/media_publish. Between them sits an asynchronous transcode you cannot see, and Meta's own reference says so plainly: "Video uploads are asynchronous, so receiving a container ID does not guarantee that the upload was successful."

The field lives on the IG Container node. Meta defines it as "The container's publishing status" and you read it with a single request:

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

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

What does each status_code value mean?

Meta documents five values and no others. The definitions below are the ones printed in the IG Container reference and repeated word for word in the Content Publishing guide.

Two of those five are terminal in the sense that no amount of waiting changes them. ERROR and EXPIRED both mean the container you are holding is dead. FINISHED is the only value that means go.

There is a second field worth requesting on the same call. copyright_check_status returns matches_found as a boolean and its own status set to completed, error, in_progress or not_started. A reel can reach FINISHED on status_code while the copyright check is still in_progress, which is one reason a publish that looked ready can still come back unhappy.

How often does Meta say to poll the container?

Meta gives a single sentence of guidance: "We recommend querying a container's status once per minute, for no more than 5 minutes." That is five requests, total, per container.

The number is worth staring at, because the same documentation sets the container's lifetime at 24 hours. Five minutes of polling covers roughly 0.35 percent of the window in which the container is valid. Meta never says what a client should do with a container that is still IN_PROGRESS at minute six. The docs simply stop.

In practice a long reel that is still transcoding at minute five is still transcoding, and the container is still good for another 23 hours and 55 minutes. The five-minute ceiling reads as advice about how hard to hammer the endpoint rather than a statement about when a container becomes hopeless. Treating it as the latter throws away containers that would have finished.

How long does an Instagram container last before it expires?

Containers expire after 24 hours. The IG User Media reference states it in its general limitations list, and the EXPIRED definition restates it from the other direction: the container "was not published within 24 hours."

The same list adds a second number that matters when you queue posts in bulk: "An Instagram account can only create 400 containers within a rolling 24 hour period." That is a container budget, not a publishing budget, and it counts every container you create whether or not you ever publish it. A retry loop that rebuilds a container on every failure burns through it fast.

The publishing budget is a separate figure, and here Meta's own guide disagrees with itself on one page. The Rate Limit section of the Content Publishing guide says "Instagram accounts are limited to 100 API-published posts within a 24-hour moving period." The carousel Limitations section, further down the same page, says "Accounts are limited to 50 published posts within a 24-hour period." Both sentences are live. Both add that a carousel counts as one post. Anyone building against this should query GET /<IG_ID>/content_publishing_limit and trust that over either paragraph, which is the approach we take in the writeup on the Instagram content publishing limit and the 100 posts per 24 hours cap.

What do you do when status_code returns ERROR?

Request the status field on the same container. Meta's definition of that field is the useful part: "Publishing status. If status_code is ERROR, this value will be an error subcode."

So status_code tells you that something broke and status tells you what. The subcodes that show up most often on a failed container come from Meta's Instagram error codes table:

The last one is the honest one. Meta's recommended fix for 2207053 is "Generate a new container and use it to try again," and it notes the subcode "should only affect video uploads."

Four of those seven are fixable before you ever create a container, by validating the file against the published specs. The caption rules are covered in the note on the 2,200 character caption limit, and the video rules in the breakdown of what the Instagram Reels API accepts.

What do you do when status_code returns EXPIRED?

Start over. There is no endpoint that revives an expired container, no extension parameter, and no update operation on the node at all. The IG Container reference says "This operation is not supported" under Creating, Updating and Deleting alike. A container is read-only from your side.

Meta's error table confirms the remedy in the recommended-solution column for subcode 2207020, whose message reads The media you are trying to access has expired. Please try to upload again. The fix given is "Generate a new container ID and use it to try again."

A related subcode is easy to confuse with expiry and is not the same thing. Subcode 2207008 returns The media builder with creation id = {creation-id} does not exist or has been expired. Meta calls this a "Temporary error publishing a container" and advises you to "Try again 1-2 times in the next 30 seconds to 2 minutes. If unsuccessful, generate a new container ID." So the message says expired, the guidance says retry. Retry before you rebuild.

Why does media_publish fail when status_code says FINISHED?

Because FINISHED describes the container, not the account. Three failures survive a clean FINISHED.

Subcode 2207027 returns The media is not ready for publishing, please wait for a moment, and Meta's fix is to check the container status and publish when it reads FINISHED, which is circular when FINISHED is exactly what you just read. Treat it as a race and retry.

Subcode 2207042 returns You reached maximum number of posts that is allowed to be published by Content Publishing API. The container is fine; the daily allowance is gone. Meta's advice is to "Advise the app's user to try again the following day."

Subcode 2207050 returns The Instagram account is restricted. Meta explains that the account "is inactive, checkpointed, or restricted" and the only path forward runs through the Instagram app, not the API. That is the same wall behind most of the reasons people find when they ask why they cannot post on Instagram.

Frequently asked questions

How many values can status_code return?

Five. IN_PROGRESS, FINISHED, PUBLISHED, ERROR and EXPIRED. Meta's IG Container reference lists exactly these and no others.

Does a photo container need polling at all?

Meta's troubleshooting section frames status polling around video, since image containers resolve on the create call. Requesting status_code on an image container still works and still returns one of the five values.

How long should you wait between polls?

Once per minute. Meta's exact wording is "We recommend querying a container's status once per minute, for no more than 5 minutes."

What happens to a container you never publish?

It expires 24 hours after creation and counts against the limit of 400 containers per rolling 24 hours. Unpublished containers do not count against the publishing limit.

Can you delete a container to free up quota?

No. The IG Container node lists Deleting as "This operation is not supported." Containers clear themselves when they expire.

Which field tells you why publishing failed?

The status field, not status_code. Meta documents that when status_code is ERROR, the status value is an error subcode you then look up in the Instagram error codes table.

How many of the ERROR subcodes can you prevent before you build a container?

Four of the seven subcodes in Meta's table are avoidable before a container even exists. Checking the file, its dimensions, and the caption length against Meta's published specs catches a wrong video format, an out-of-range aspect ratio, an oversized image, or an overlong caption before you upload, since every one of those conditions is already known before you create the container.

Can a container reach FINISHED before the copyright check finishes?

Yes. A reel can hit FINISHED on status_code while copyright_check_status is still in_progress, so the container looks ready before the copyright review has actually resolved. That field returns matches_found as a boolean plus a status of completed, error, in_progress, or not_started, and it's worth requesting alongside status_code before you publish.

Why does Meta's own documentation disagree on the publishing limit?

The Rate Limit section of the Content Publishing guide caps accounts at 100 API-published posts within a 24-hour moving period, while the carousel Limitations section further down the same page puts the cap at 50 published posts within 24 hours. Both sentences are still live in Meta's docs. Querying GET /<IG_ID>/content_publishing_limit and trusting that response over either paragraph avoids the guesswork.

Does subcode 2207008 mean the container has expired?

No, even though its message reads "has been expired." Meta classifies 2207008 as a temporary error and recommends retrying once or twice over the next 30 seconds to 2 minutes before building a new container. An actual EXPIRED status has no retry path at all.