Instagram Reels API ProcessingFailedError: causes and fixes
ProcessingFailedError on an Instagram Reel published through the API means Meta could not finish processing the video inside the upload request to rupload.facebook.com. There are two common causes. The first is time. In our tests, the resumable upload path gave up after about 35 seconds of processing, so long reels failed even though the files were valid. The second is a malformed file, most often audio and video tracks of different lengths. For the first, create the container with video_url so Meta processes the video in the background, then poll status_code until it reads FINISHED. For the second, re-encode the file before you upload it.
What does the ProcessingFailedError response look like?
The error comes back from the upload call, not from creating the container. You create a Reels container with upload_type=resumable, send the bytes to rupload.facebook.com/ig-api-upload/<API_VERSION>/<CONTAINER_ID>, and instead of {"success": true} you get an HTTP 400 with a body shaped like this:
{
"debug_info": {
"retriable": false,
"type": "ProcessingFailedError",
"message": "{\"success\":false,\"error\":{\"message\":\"...\"}}"
}
}
Meta’s content publishing guide shows this exact shape for a failed resumable upload. ProcessingFailedError is only a wrapper. Meta’s own example nests “unauthorized user request” inside it, so log the nested message and read it before you guess.
One detail cost us time. After the 400, the container we had created never left IN_PROGRESS while we polled it. Don’t wait for it to recover. Create a new container for the next attempt.
Why does a valid reel fail with ProcessingFailedError?
A valid reel fails when Meta’s processing takes longer than the upload request is allowed to stay open. The rupload endpoint processes the video during the request itself. Meta’s docs don’t publish that limit, so we measured it. In October 2026 we ran non-publishing probes against our own Instagram account: create a container, upload with rupload, time the response, and never call media_publish.
| What we varied | What happened |
|---|---|
| Uploads that passed | Answered in 26 seconds or less |
| Uploads that failed | HTTP 400 ProcessingFailedError at 35 to 37 seconds |
| File size and H.264 level | No effect on pass or fail |
The same 102 MB, 70 second reel sent via video_url |
Reached FINISHED after 64 seconds |
So a 70 second reel needs roughly a minute of processing, and the upload request gives up after about 35. It passes only on the rare run where Meta is unusually quick. Short reels usually fit inside the window, which is why the failure looks intermittent. In August we read it as a bad spell on Meta’s side and added a retry window. The October measurements showed the real mechanism. Treat the 35 second figure as our observation, not a documented Meta limit.
How do I fix it with video_url?
Create the container with video_url instead of upload_type=resumable. Meta then downloads the file and processes it asynchronously, so no request has to stay open while it works. Our engine runs the same three calls. Here they are as curl, with placeholders for every id and token:
# 1. Create the Reels container from a public URL
curl -X POST "https://graph.facebook.com/v24.0/<IG_USER_ID>/media" \
-d "media_type=REELS" \
-d "video_url=https://media.example.com/reel.mp4" \
-d "caption=Your caption" \
-d "access_token=<ACCESS_TOKEN>"
# -> {"id":"<CONTAINER_ID>"}
# 2. Poll until status_code is FINISHED
curl "https://graph.facebook.com/v24.0/<CONTAINER_ID>?fields=status_code,status&access_token=<ACCESS_TOKEN>"
# 3. Publish the finished container
curl -X POST "https://graph.facebook.com/v24.0/<IG_USER_ID>/media_publish" \
-d "creation_id=<CONTAINER_ID>" \
-d "access_token=<ACCESS_TOKEN>"
The URL is where most video_url problems start. Meta’s IG User Media reference says Meta fetches the file with a cURL-style request, so it has to sit on a public server at the moment of the attempt. A presigned object storage URL is fine (our hosted runtime uses one). A URL behind a login, or one that redirects to a sign-in page, is not.
The URL also has to return the video itself. We learned this one the hard way with images: a mirrored file got renamed, the URL started serving an HTML 404 page, and Meta answered every attempt with error 9004, “Only photo or video can be accepted as media type”, until we fixed the file name. And give a presigned URL a few minutes of life at least, since our 70 second reel took 64 seconds to process.
If the download itself fails, Meta’s error code table lists code 9004 with subcode 2207052 (“The media could not be fetched from this uri”) and code -2 with subcode 2207003 (“It takes too long to download the media”).
How long should I poll the container status_code?
Poll until status_code reads FINISHED, and stop on ERROR or EXPIRED. Meta’s troubleshooting advice is once per minute for no more than five minutes. The IG Container reference defines five values:
| status_code | Meaning |
|---|---|
IN_PROGRESS |
Still processing |
FINISHED |
Ready to publish |
ERROR |
Processing failed; the status field carries a subcode |
EXPIRED |
Not published within 24 hours |
PUBLISHED |
Already published |
Our 70 second reel needed 64 seconds through video_url. We wait up to ten minutes for video_url reels and five for everything else, then report the container as stuck. If you call media_publish too early you get code 9007, subcode 2207027, “The media is not ready for publishing”. Keep polling, then publish once the container reads FINISHED.
What video specs does Instagram require for Reels?
As of November 2026, Meta’s IG User Media reference lists these Reels specifications:
| Property | Requirement |
|---|---|
| Container | MOV or MP4, moov atom at the front, no edit lists |
| Video codec | H.264 or HEVC, progressive scan, closed GOP, 4:2:0 chroma |
| Audio codec | AAC, 48 kHz maximum, mono or stereo, 128 kbps |
| Frame rate | 23 to 60 FPS |
| Width | 1920 pixels maximum |
| Aspect ratio | 0.01:1 to 10:1 (9:16 recommended) |
| Video bitrate | VBR, 25 Mbps maximum |
| Duration | 3 seconds to 15 minutes |
| File size | 300 MB maximum |
Meta’s list leaves out one check that we learned from a failed post: the audio and video tracks need the same length. One reel had a 5.0 second gap between its audio and video tracks, and rupload rejected it with a ProcessingFailedError every time. After a re-encode the drift was 0.03 seconds and the reel published. Check the per-stream durations, not the container duration, which only reports the longer stream:
ffprobe -v error -show_entries stream=codec_type,duration -of csv=p=0 reel.mp4
# video,10.000000
# audio,5.000000
To pad the audio out to the video’s length and move the moov atom to the front in one pass:
ffmpeg -i reel.mp4 -c:v libx264 -pix_fmt yuv420p -af apad -c:a aac -ar 48000 \
-shortest -movflags +faststart reel-fixed.mp4
On our 10 second test file this brought the drift from 5 seconds down to 0.016. Drop -af apad if you would rather cut the video to the audio’s length.
Should I retry a ProcessingFailedError?
Find the cause before you retry. A malformed file fails every time, so fix the file. A timeout on a valid file can pass on a later attempt, despite retriable:false, but you are betting on Meta happening to process it quickly. For a long reel, switch to video_url instead of retrying. If you have to stay on rupload (for example because the video only exists on a laptop), retry with backoff over a bounded window and create a new container each time. pendpost treats this error as temporary and backs off for up to about three hours before it parks the post and tells you why.
How does pendpost handle Instagram Reels?
pendpost’s Meta engine creates the Reels container with video_url whenever it has an https address for the video. The optional hosted runtime supplies a presigned one, so long reels go through the asynchronous path. A purely local install has no public URL for a file on your disk, so it still uses the resumable upload. On that path, long reels can hit the timeout described above.
When you attach a reel, pendpost probes the file and flags a non-H.264 codec and a missing faststart flag, and its readiness check marks a reel whose audio and video tracks are more than a second apart as not ready to publish. An agent gets the same checks over MCP through validate_media and platform_validate. You can try the whole draft, check, approve, publish loop without a Meta account in mock mode. The Meta token setup is in the Meta credentials guide, and the full lane list is on the capabilities page. If an agent drafts your reels, the approval gate means none of them publishes until you approve it.
Reel publishing checklist
- Probe the file: MP4 or MOV, H.264 or HEVC with yuv420p, AAC audio, faststart, 3 seconds to 15 minutes, under 300 MB.
- Compare the audio and video stream durations. More than a second apart means re-encode.
- For long reels, host the file at a public URL and use
video_url. In our tests a 70 second reel almost never passed rupload, while a 30 second cut did. - Make sure the URL returns the video itself, with no login, no HTML error page, and enough lifetime.
- Poll
status_codeuntilFINISHED. OnERROR, read the subcode instatus. - On a rupload
ProcessingFailedError, check the reel’s length before you suspect the encoding. - Never reuse a container after a failed upload. Create a new one.
Frequently asked questions
What does ProcessingFailedError mean on the Instagram API?
It is the error type Meta returns in debug_info when an upload to rupload.facebook.com fails during processing. The type is a wrapper, so the nested message field says more about the specific failure. For valid reels the usual cause is that processing took longer than the upload request allows; for broken files it is usually a malformed mux such as mismatched audio and video lengths.
Is ProcessingFailedError a temporary error?
Sometimes. Meta labels it retriable:false, and for a malformed file that is accurate: retrying the same bytes never helps. When the cause is the processing time limit, the same file can pass on a later attempt if Meta happens to process it fast enough, which is why the error can look random. The reliable fix for long reels is the video_url path, not more retries.
Do I need a public URL to publish an Instagram Reel through the API?
Not strictly. You can pass a public video_url, which Meta downloads itself, or use a resumable upload session that sends the bytes from your own disk. Meta's docs say only apps that implement Facebook Login for Business can use resumable uploads. The public URL path is the one that copes with long reels, because processing runs after the request returns.
How long should I poll an Instagram media container?
Meta's publishing guide suggests checking status_code once per minute for no more than five minutes. In our tests a 70 second reel needed 64 seconds of processing through video_url, so a short reel is usually ready inside the first check. We give video_url reels up to ten minutes before treating the container as stuck.
What video format does the Instagram API accept for Reels?
As of November 2026, Meta's reference lists MOV or MP4 with the moov atom at the front, H.264 or HEVC video with 4:2:0 chroma, AAC audio at up to 48 kHz, 23 to 60 frames per second, up to 1920 pixels wide, 3 seconds to 15 minutes long and at most 300 MB. Meta recommends a 9:16 aspect ratio.
Sources
- Meta: Instagram Platform content publishing guide
- Meta: IG User Media reference (Reels specifications, video_url, resumable upload)
- Meta: IG Container reference (status_code values)
- Meta: Instagram Platform error codes
pendpost is free and open source. Try the whole draft, approve and publish loop in mock mode, with no real API calls.