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.
Content, carousel, and product tagging errors
Content errors are about the caption and how the post is perceived. Code 2207010 means the caption is longer than 2,200 characters, including hashtags and mentions; trim the caption or move overflow into a first-comment reply. Code 2207001 means Instagram flagged the post as spam, which can happen with repeated identical posts, excessive hashtags, suspicious link patterns, or copy-paste promotional language; rewrite the caption in fresh wording, keep hashtags below 15, and spread similar posts across accounts and time instead of sending them together. Carousel validation error 2207028 means carousel validation failed, usually because of mixed media types, inconsistent aspect ratios, or a slide count outside the 2 to 10 range; build the carousel with between 2 and 10 slides, give every slide the same aspect ratio, and do not combine photos and videos in one carousel. Product tagging errors follow coordinate rules. Code 2207035 means position-based product tags are not allowed on videos, because Instagram only supports positioned product tags on photos and videos accept un-positioned tags only; drop x and y coordinates for video posts. Code 2207036 means position data is missing on a photo product tag, because photo posts require explicit x and y values from 0.0 to 1.0 for every product tag; provide normalized coordinates for each tagged product. Code 2207037 means product tag validation failed, because a product ID does not exist in the connected catalog or a coordinate is outside 0 to 1; cross-check product IDs against the Commerce Catalog and clamp coordinates. Code 2207040 means there are too many product tags on the post, because Instagram caps tags at 5 per image; pick the 5 most relevant products.
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.
| Code | Category | What it means |
|---|---|---|
| REVOKED_ACCESS_TOKEN | Authentication | Your Instagram access token was revoked. |
| session_invalidated | Authentication | Instagram invalidated the session token. |
| token_validation_error | Authentication | User is not a confirmed Instagram/Facebook user. |
| not_business_account | Authentication | The account is not a Business or Creator account. |
| 2207050 | Authentication | Instagram restricted the account from publishing. |
| permission_error | Authentication | The app lacks one of the required publishing permissions. |
| 2207003 | Media upload | Instagram timed out downloading your media URL. |
| 2207020 | Media upload | The media container expired before publishing. |
| 2207032 | Media upload | Container creation failed inside Instagram. |
| 2207053 | Media upload | Generic "unknown upload error" from Instagram. |
| 2207052 | Media upload | Instagram could not fetch the media URL. |
| 2207006 | Media upload | The container ID you tried to publish is gone. |
| 2207008 | Media upload | Media builder expired between create and publish. |
| 2207027 | Media upload | Instagram returned an unspecified error. |
| 2207004 | Media format | Image file is over 8MB. |
| 2207005 | Media format | Image format is not JPG or PNG. |
| 2207009 | Media format | Aspect ratio is outside the supported range (4:5 to 1.91:1). |
| 36003 | Media format | Aspect ratio is outside the supported range. |
| 36001 | Media format | Image resolution exceeds 1920×1080. |
| 2207026 | Media format | Video format is not MP4 with H.264/AAC. |
| 2207057 | Media format | Thumbnail offset is outside the video duration. |
| 2207023 | Media format | Instagram could not determine the media type. |
| 2207010 | Content | Caption is longer than 2,200 characters. |
| 2207001 | Content | Instagram flagged the post as spam. |
| 2207051 | Rate limit | Instagram blocked the request as suspicious. |
| 2207028 | Carousel | Carousel validation failed. |
| 2207035 | Product tagging | Position-based product tags are not allowed on videos. |
| 2207036 | Product tagging | Position data is missing on a photo product tag. |
| 2207037 | Product tagging | Product tag validation failed. |
| 2207040 | Product tagging | Too many product tags on the post. |
| 9 | Rate limit | User is performing too many actions. |
| page_request_limit | Rate limit | The connected account hit a platform request limit. |
| 2207042 | Rate limit | Rolling 24-hour API publishing quota reached. |
| unknown_error | Server | Generic Instagram service error. |
Lookup table preserved from source for Ctrl/Cmd-F use.
| Code | Category | Likely cause | Retryability | First fix action |
|---|---|---|---|---|
| REVOKED_ACCESS_TOKEN | Authentication | Token revoked or app removed | No — reconnect | Disconnect and run OAuth again |
| session_invalidated | Authentication | Password change, security challenge, forced logout | No — reconnect | Reconnect account |
| token_validation_error | Authentication | Meta account not confirmed | No — reconnect after confirmation | Finish confirmation, then reconnect |
| not_business_account | Authentication | Not a Professional account linked to a Facebook Page | No — change account type | Convert to Professional and link Page |
| 2207050 | Authentication | Account restricted from publishing | No — resolve restriction | Check app notice, identity check, appeal |
| permission_error | Authentication | Required scope not granted | No — reconnect with scopes | Restart connect flow, grant all scopes |
| 2207003 | Media upload | Media URL download timed out | Retry after fixing host | Use fast CDN, public URL, smaller file |
| 2207020 | Media upload | Container expired after 24 hours | No — recreate | Recreate and publish in same workflow |
| 2207032 | Media upload | Container creation failed in ingestion | Retry after re-encode | Re-encode to supported specs |
| 2207053 | Media upload | Unknown upload error, likely corruption | Retry with new export | Re-export from original master |
| 2207052 | Media upload | Media URL not fetchable (non-200, wrong Content-Type, zero bytes) | Retry after fixing URL | Verify with curl, Content-Type, 200 without auth |
| 2207006 | Media upload | Container ID gone (expired, published, or wrong) | No — recreate | Recreate container and publish promptly |
| 2207008 | Media upload | Media builder per-step timeout | No — recreate tightly | Keep create-then-publish flow tight |
| 2207027 | Media upload | Unspecified transient ingestion failure | Retry with backoff | Exponential backoff; if persistent, check media/account |
| 2207004 | Media format | Image over 8MB | No — re-export | Compress or downscale under 8MB |
| 2207005 | Media format | Image not JPG or PNG | No — convert | Convert to JPG or PNG |
| 2207009 | Media format | Aspect ratio outside 4:5 to 1.91:1 | No — crop/pad | Crop or pad, 1:1 default |
| 36003 | Media format | Aspect ratio outside supported range (other path) | No — crop/pad | Use 1:1, 4:5, or 1.91:1 |
| 36001 | Media format | Resolution over 1920px long edge | No — downscale | Downscale long edge to 1920px |
| 2207026 | Media format | Video not MP4 H.264/AAC | No — re-encode | FFmpeg libx264/aac re-encode |
| 2207057 | Media format | thumb_offset outside video duration | No — fix field | Set 0..duration_ms or null |
| 2207023 | Media format | media_type missing or mismatched | No — fix field | Send correct media_type |
| 2207010 | Content | Caption over 2,200 characters | No — trim | Trim caption or move overflow to first comment |
| 2207001 | Content | Post flagged as spam | No — rephrase | Rephrase, under 15 hashtags, vary posts |
| 2207051 | Rate limit | Request blocked as suspicious | Wait 15-30 minutes | Pause and slow cadence |
| 2207028 | Carousel | Carousel validation failed | No — fix structure | 2-10 items, same ratio, no mixed types |
| 2207035 | Product tagging | Positioned tags on video | No — remove coordinates | Drop x/y for videos |
| 2207036 | Product tagging | Missing x/y on photo tag | No — add coordinates | Provide normalized x/y 0.0-1.0 |
| 2207037 | Product tagging | Bad product ID or coordinate out of range | No — fix data | Check catalog IDs, clamp coordinates |
| 2207040 | Product tagging | Over 5 tags per image | No — reduce tags | Keep 5 most relevant products |
| 9 | Rate limit | Too many actions, account throttled | Wait, then retry/reschedule | Pause publishing; do not retry immediately |
| page_request_limit | Rate limit | Account-level platform request limit | Wait for recovery | Pause and retry after limit recovers |
| 2207042 | Rate limit | Rolling 24-hour API publishing quota reached | Wait for window | Wait for posts to leave rolling window |
| unknown_error | Server | Transient Meta internal failure | Retry with backoff | Exponential backoff, usually resolves in 2-3 attempts |
Retryability is guidance from the source descriptions, not a tested runtime guarantee.
| Field | Applies to | Required rule | Error codes | Fix |
|---|---|---|---|---|
| format | Images | JPG or PNG only | 2207005 | Convert HEIC/WebP/GIF/TIFF to JPG/PNG |
| size_mb | Images | 8MB maximum | 2207004 | Re-export or compress under 8MB |
| aspect_ratio | Feed images | 4:5 to 1.91:1 | 2207009, 36003 | Crop or pad; 1:1 is safe default |
| long_edge_px | Feed images | 1920px maximum | 36001 | Downscale long edge to 1920px |
| video_codec / audio_codec | Video | MP4 H.264 video, AAC audio | 2207026 | FFmpeg: -c:v libx264 -c:a aac |
| media_type | All media | IMAGE, VIDEO, REELS, or CAROUSEL; must match file | 2207023 | Send correct media_type |
| thumb_offset | Video | 0 to duration in ms, or null | 2207057 | Clamp to duration or leave null |
| caption | All posts | 2,200 characters maximum | 2207010 | Trim or move overflow to first comment |
| carousel items | Carousel | 2-10 items, same aspect ratio, no mixed image/video | 2207028 | Normalize items before creating container |
| product tag x/y | Photo product tags | Required, 0.0-1.0; not allowed on video; max 5 tags | 2207035, 2207036, 2207037, 2207040 | Add/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.
| Step | What happens | Failure check |
|---|---|---|
| 1. Create container | Submit 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 container | Publish 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 promptly | Create 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 fails | Container 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.