Skip to content

Instagram API errors

Instagram API errors are easiest to fix when you first identify which layer rejected the request. Instagram's Content Publishing stack can return errors from the Graph API gateway, the media container builder, and the ingestion pipeline, and each layer uses its own code scheme. This guide covers 34 documented Instagram API errors across authentication, media upload, media format, content, carousel, product tagging, rate limit, and server categories, with a plain-English cause and a first fix action for each code. Start by finding your exact code in the quick reference table, then read the category section for the checks that usually resolve it.

Instagram API errors: how to find your code

Instagram API errors fall into eight categories. Authentication errors mean the account, token, or permission is the problem, so reconnecting or fixing account type comes before retrying a publish. Media upload errors mean the container lifecycle or the fetch of your media URL failed. Media format errors mean the file itself does not match Instagram's ingestion specs, even if the URL is reachable. Content errors cover caption length and spam flags. Carousel and product tagging errors are validation failures on structure and coordinates. Rate limit errors mean you should wait rather than retry immediately. Server errors are usually transient and are the main category where retry with backoff is appropriate. The failure matrix below maps every code to its category, likely cause, retryability, and first fix action so you can decide quickly whether to reconnect, re-encode, recreate a container, or wait.

Authentication errors: reconnect and account type checks

Authentication errors require a fresh grant or an account change; retrying the same publish will not help. REVOKED_ACCESS_TOKEN means the Instagram access token was revoked, commonly because the connected user removed the app from Instagram Settings under Apps and Websites, or Meta invalidated the token for security reasons. The fix is to disconnect the integration and run the Instagram OAuth flow again to store a fresh long-lived token. session_invalidated means Instagram invalidated the session token, for example after a password change, a security challenge, or a forced logout across devices. There is no programmatic recovery, so reconnect the account. token_validation_error means the user is not a confirmed Instagram or Facebook user, often because email or phone confirmation is incomplete or a security check is pending; have the user finish confirmation in the Instagram or Facebook app, then reconnect. not_business_account means the account is not a Business or Creator account, and the Content Publishing API only accepts Professional accounts linked to a Facebook Page, so convert the account to Professional in Instagram Settings under Account type and connect it to a Facebook Page. Code 2207050 means Instagram restricted the account from publishing after a community-standards violation or automated risk check; check the notice shown in the Instagram app, finish any identity verification it asks for, and submit an appeal where that option is offered. permission_error means the app lacks a required publishing permission, typically instagram_content_publish, pages_show_list, or business_management, because a scope was not granted during OAuth; restart the connect flow and grant every requested permission, since Meta hides scopes from the consent screen if the user deselects them. A useful check before reconnecting is to confirm account type, confirmation status, and granted scopes, because each of those maps to a different code above.

Media upload errors: container expiry, fetch failures, and ingestion

Media upload errors are about the container lifecycle and whether Instagram could fetch your asset. Code 2207003 means Instagram timed out downloading your media URL, usually because the image_url or video_url responded too slowly or the file was too large for the pull; serve the file from a quick CDN, make the link reachable without login, and keep the file within Instagram's size limits. Code 2207020 means the media container expired before publishing, because Instagram only keeps a container creation alive for 24 hours and the publish step ran after the window closed; always publish the container in the same workflow that created it, or recreate it before retrying. Code 2207032 means container creation failed inside Instagram, often because the media did not match ingestion specs for codec, resolution, or aspect ratio, or because of a transient ingestion error; re-encode to JPEG or PNG for images or MP4 H.264/AAC for video at a supported aspect ratio, then retry. Code 2207053 is a generic unknown upload error from Instagram's ingestion pipeline, usually file corruption or an edge case without a specific reason; try a different export re-encoded from the original master. Code 2207052 means Instagram could not fetch the media URL, because the response was not a success status, the Content-Type header did not match the asset, or the file contained no bytes; test the link with curl, check that Content-Type matches the asset such as image/jpeg or video/mp4, and confirm it returns 200 without authentication. Code 2207006 means the container ID you tried to publish is gone, because it expired under the 24-hour limit, was already published, or the ID is wrong; recreate the container from the source media and publish it before the window closes. Code 2207008 means the media builder expired between create and publish because too much time passed inside the container-creation flow itself and hit the per-step timeout, which is separate from the 24-hour container timeout; keep the create-then-publish flow tight and do not wait on user confirmation in the middle. Code 2207027 is an unspecified error and a catch-all for transient ingestion failures; retry with exponential backoff, and if it persists across attempts, treat the underlying media or account state as the actual problem. The worked example below traces a publish from container creation through expiry to recreation, which is the pattern behind 2207020, 2207006, and 2207008.

Media format errors: size, format, aspect ratio, resolution, and codec

Media format errors are rejected before or during ingestion, and the field map below gives the exact limits to check. Code 2207004 means the image file is over 8MB, because the Graph API caps photo uploads at 8MB; re-export at lower quality or smaller dimensions, or compress the file to drop under 8MB. Code 2207005 means the image format is not JPG or PNG, because the Content Publishing ingestion path turns away formats such as HEIC, WebP, GIF and TIFF; convert the file to JPG or PNG before submitting. Code 2207009 means the aspect ratio is outside the supported range of 4:5 to 1.91:1 for feed posts; crop or pad the image into range, with 1:1 square as the safe default. Code 36003 is the same aspect ratio constraint surfaced from a different ingestion path, so use 1:1, 4:5, or 1.91:1. Code 36001 means image resolution exceeds 1920 by 1080, because feed images larger than 1920px on the long edge are rejected; downscale to 1920px maximum on the long edge. Code 2207026 means the video format is not MP4 with H.264/AAC, because Instagram only ingests MP4 with H.264 video and AAC audio and does not accept HEVC, VP9, AV1, or Opus; re-encode with FFmpeg using ffmpeg -i in.mov -c:v libx264 -c:a aac out.mp4. Code 2207057 means the thumbnail offset is outside the video duration, because thumb_offset was larger than the video length in milliseconds; use a value between 0 and the video duration in milliseconds, or leave it null to let Instagram pick. Code 2207023 means Instagram could not determine the media type, because media_type was missing or mismatched the actual file format; send the correct media_type value of IMAGE, VIDEO, REELS, or CAROUSEL. Checking format, size, aspect ratio, resolution, codec, media_type, and thumb_offset before creating a container prevents most of these errors.

Rate limit and server errors: when to wait and when to retry

Rate limit and server errors require different decisions. Code 2207051 means Instagram blocked the request as suspicious, often after burst posting, high request volume from a single account, or unusual device or IP behavior triggered Meta's anti-abuse layer; pause posting for 15 to 30 minutes and slow down your cadence. Error 9 means the user is performing too many actions, because Instagram temporarily throttled the account after a burst of publishing actions, and activity from other tools connected to the same account can contribute; pause publishing, then retry or reschedule the failed post later, and do not retry immediately because repeated attempts can extend the throttle. page_request_limit means the connected account hit a platform request limit based on recent API activity; pause publishing and retry after the account request limit recovers. Code 2207042 means the rolling 24-hour API publishing quota was reached, and posts published through other schedulers can contribute to that quota; let earlier API posts age out of the rolling 24-hour window, then retry or reschedule the failed post. Code unknown_error is a generic Instagram service error from a transient internal failure on Meta's side; retry with exponential backoff, because most of these resolve on the second or third attempt. The decision rule is simple: reconnect for authentication codes, re-encode or recreate for format and upload codes, wait for rate limit and quota codes, and retry with backoff only for transient server and unspecified ingestion codes such as unknown_error and 2207027.

Quick reference table: all 34 codes

Use the quick reference table below to find any of the 34 codes with Ctrl or Cmd-F. If your code is not listed, check whether the response came from a different layer, such as the Graph API gateway, and record the full code, category, and timestamp before retrying. For container codes, note when the container was created so you can tell whether the 24-hour window has closed. For format codes, note the file's format, size, aspect ratio, resolution, and codec so you can re-encode once instead of guessing. For rate limit codes, note the account and the time of the burst so you can wait for the relevant window instead of retrying immediately.

Quick reference: all 34 Instagram API errors
CodeCategoryWhat it means
REVOKED_ACCESS_TOKENAuthenticationYour Instagram access token was revoked.
session_invalidatedAuthenticationInstagram invalidated the session token.
token_validation_errorAuthenticationUser is not a confirmed Instagram/Facebook user.
not_business_accountAuthenticationThe account is not a Business or Creator account.
2207050AuthenticationInstagram restricted the account from publishing.
permission_errorAuthenticationThe app lacks one of the required publishing permissions.
2207003Media uploadInstagram timed out downloading your media URL.
2207020Media uploadThe media container expired before publishing.
2207032Media uploadContainer creation failed inside Instagram.
2207053Media uploadGeneric "unknown upload error" from Instagram.
2207052Media uploadInstagram could not fetch the media URL.
2207006Media uploadThe container ID you tried to publish is gone.
2207008Media uploadMedia builder expired between create and publish.
2207027Media uploadInstagram returned an unspecified error.
2207004Media formatImage file is over 8MB.
2207005Media formatImage format is not JPG or PNG.
2207009Media formatAspect ratio is outside the supported range (4:5 to 1.91:1).
36003Media formatAspect ratio is outside the supported range.
36001Media formatImage resolution exceeds 1920×1080.
2207026Media formatVideo format is not MP4 with H.264/AAC.
2207057Media formatThumbnail offset is outside the video duration.
2207023Media formatInstagram could not determine the media type.
2207010ContentCaption is longer than 2,200 characters.
2207001ContentInstagram flagged the post as spam.
2207051Rate limitInstagram blocked the request as suspicious.
2207028CarouselCarousel validation failed.
2207035Product taggingPosition-based product tags are not allowed on videos.
2207036Product taggingPosition data is missing on a photo product tag.
2207037Product taggingProduct tag validation failed.
2207040Product taggingToo many product tags on the post.
9Rate limitUser is performing too many actions.
page_request_limitRate limitThe connected account hit a platform request limit.
2207042Rate limitRolling 24-hour API publishing quota reached.
unknown_errorServerGeneric Instagram service error.

Lookup table preserved from source for Ctrl/Cmd-F use.

Failure matrix: all 34 Instagram API errors
CodeCategoryLikely causeRetryabilityFirst fix action
REVOKED_ACCESS_TOKENAuthenticationToken revoked or app removedNo — reconnectDisconnect and run OAuth again
session_invalidatedAuthenticationPassword change, security challenge, forced logoutNo — reconnectReconnect account
token_validation_errorAuthenticationMeta account not confirmedNo — reconnect after confirmationFinish confirmation, then reconnect
not_business_accountAuthenticationNot a Professional account linked to a Facebook PageNo — change account typeConvert to Professional and link Page
2207050AuthenticationAccount restricted from publishingNo — resolve restrictionCheck app notice, identity check, appeal
permission_errorAuthenticationRequired scope not grantedNo — reconnect with scopesRestart connect flow, grant all scopes
2207003Media uploadMedia URL download timed outRetry after fixing hostUse fast CDN, public URL, smaller file
2207020Media uploadContainer expired after 24 hoursNo — recreateRecreate and publish in same workflow
2207032Media uploadContainer creation failed in ingestionRetry after re-encodeRe-encode to supported specs
2207053Media uploadUnknown upload error, likely corruptionRetry with new exportRe-export from original master
2207052Media uploadMedia URL not fetchable (non-200, wrong Content-Type, zero bytes)Retry after fixing URLVerify with curl, Content-Type, 200 without auth
2207006Media uploadContainer ID gone (expired, published, or wrong)No — recreateRecreate container and publish promptly
2207008Media uploadMedia builder per-step timeoutNo — recreate tightlyKeep create-then-publish flow tight
2207027Media uploadUnspecified transient ingestion failureRetry with backoffExponential backoff; if persistent, check media/account
2207004Media formatImage over 8MBNo — re-exportCompress or downscale under 8MB
2207005Media formatImage not JPG or PNGNo — convertConvert to JPG or PNG
2207009Media formatAspect ratio outside 4:5 to 1.91:1No — crop/padCrop or pad, 1:1 default
36003Media formatAspect ratio outside supported range (other path)No — crop/padUse 1:1, 4:5, or 1.91:1
36001Media formatResolution over 1920px long edgeNo — downscaleDownscale long edge to 1920px
2207026Media formatVideo not MP4 H.264/AACNo — re-encodeFFmpeg libx264/aac re-encode
2207057Media formatthumb_offset outside video durationNo — fix fieldSet 0..duration_ms or null
2207023Media formatmedia_type missing or mismatchedNo — fix fieldSend correct media_type
2207010ContentCaption over 2,200 charactersNo — trimTrim caption or move overflow to first comment
2207001ContentPost flagged as spamNo — rephraseRephrase, under 15 hashtags, vary posts
2207051Rate limitRequest blocked as suspiciousWait 15-30 minutesPause and slow cadence
2207028CarouselCarousel validation failedNo — fix structure2-10 items, same ratio, no mixed types
2207035Product taggingPositioned tags on videoNo — remove coordinatesDrop x/y for videos
2207036Product taggingMissing x/y on photo tagNo — add coordinatesProvide normalized x/y 0.0-1.0
2207037Product taggingBad product ID or coordinate out of rangeNo — fix dataCheck catalog IDs, clamp coordinates
2207040Product taggingOver 5 tags per imageNo — reduce tagsKeep 5 most relevant products
9Rate limitToo many actions, account throttledWait, then retry/reschedulePause publishing; do not retry immediately
page_request_limitRate limitAccount-level platform request limitWait for recoveryPause and retry after limit recovers
2207042Rate limitRolling 24-hour API publishing quota reachedWait for windowWait for posts to leave rolling window
unknown_errorServerTransient Meta internal failureRetry with backoffExponential backoff, usually resolves in 2-3 attempts

Retryability is guidance from the source descriptions, not a tested runtime guarantee.

Media validation field map
FieldApplies toRequired ruleError codesFix
formatImagesJPG or PNG only2207005Convert HEIC/WebP/GIF/TIFF to JPG/PNG
size_mbImages8MB maximum2207004Re-export or compress under 8MB
aspect_ratioFeed images4:5 to 1.91:12207009, 36003Crop or pad; 1:1 is safe default
long_edge_pxFeed images1920px maximum36001Downscale long edge to 1920px
video_codec / audio_codecVideoMP4 H.264 video, AAC audio2207026FFmpeg: -c:v libx264 -c:a aac
media_typeAll mediaIMAGE, VIDEO, REELS, or CAROUSEL; must match file2207023Send correct media_type
thumb_offsetVideo0 to duration in ms, or null2207057Clamp to duration or leave null
captionAll posts2,200 characters maximum2207010Trim or move overflow to first comment
carousel itemsCarousel2-10 items, same aspect ratio, no mixed image/video2207028Normalize items before creating container
product tag x/yPhoto product tagsRequired, 0.0-1.0; not allowed on video; max 5 tags2207035, 2207036, 2207037, 2207040Add/clamp coordinates, verify catalog IDs, cap at 5

Limits are as documented in the source; verify against current platform documentation before relying on them for new integrations.

Worked example: container creation through expiry to recreation
StepWhat happensFailure check
1. Create containerSubmit media URL, media_type, and caption; Instagram starts a container with a 24-hour lifetime.If 2207023, fix media_type; if 2207004/2207005/2207009/36001/2207026, re-encode first.
2. Wait for user confirmation (illustrative)Workflow pauses before publishing.If the pause plus queue time exceeds the per-step timeout, expect 2207008; if total age exceeds 24 hours, expect 2207020.
3. Publish containerPublish step runs against the stored container ID.If 2207006, the ID expired, was already published, or is wrong — recreate from source media.
4. Recreate and publish promptlyCreate a fresh container and publish in the same workflow without an intervening user wait.Confirm the media URL returns 200 with correct Content-Type (2207052) and that the file meets format limits before recreating.
5. If ingestion failsContainer creation or publish returns 2207032, 2207053, or 2207027.Re-encode from the master; retry 2207027 with exponential backoff, and treat persistence as a media or account problem.

Illustrative trace based on documented container lifecycle; not a claim of executed runtime behavior. Step 2 is an illustrative extrapolation of the source guidance not to wait on user confirmation mid-flow.