Instagram API Errors

Your Instagram access token was revoked.

Why it happens

The connected user removed the app from Instagram → Settings → Apps and Websites, or Meta invalidated the token for security reasons.

How to fix

Disconnect the integration and run the Instagram OAuth flow again. PostPeer will store a fresh long-lived token.

How PostPeer handles it

PostPeer surfaces this as a clean "reconnect required" state on the integration so your end-users see a single CTA, not a 500.

Instagram invalidated the session token.

Why it happens

The user changed their password, completed a security challenge, or Meta forced a logout across their devices.

How to fix

Reconnect the account. There is no programmatic recovery — Meta requires a fresh OAuth grant.

User is not a confirmed Instagram/Facebook user.

Why it happens

The underlying Meta account has not completed email/phone confirmation, or a security check is pending.

How to fix

Have the user finish account confirmation in the Instagram or Facebook app, then reconnect.

The account is not a Business or Creator account.

Why it happens

The Instagram Content Publishing API only accepts posts from Professional accounts linked to a Facebook Page.

How to fix

Convert the account to Professional in Instagram Settings → Account type, then connect it to a Facebook Page.

How PostPeer handles it

PostPeer's connect flow checks the account type before storing the integration and tells the user up-front if a conversion is needed.

Instagram restricted the account from publishing.

Why it happens

A community-standards violation or automated risk check led Meta to block the account from posting through the API.

How to fix

Open the Instagram app to see the restriction notice, complete any required identity check, and appeal if appropriate.

The app lacks one of the required publishing permissions.

Why it happens

A required scope (typically `instagram_content_publish`, `pages_show_list`, or `business_management`) was not granted during OAuth.

How to fix

Restart the connect flow and grant every requested permission — Meta hides scopes from the consent screen if the user deselects them.

Instagram timed out downloading your media URL.

Why it happens

Instagram fetched the `image_url` or `video_url` you supplied and either it responded too slowly or the file was too large for the pull.

How to fix

Host the asset on a fast CDN, ensure the URL is publicly reachable, and keep file sizes inside Instagram's limits.

How PostPeer handles it

PostPeer signs and caches media on our CDN before handing the URL to Instagram, so customer assets rarely trip this.

The media container expired before publishing.

Why it happens

Instagram only keeps a container creation alive for 24 hours. The publish step ran after the window closed.

How to fix

Always publish the container in the same workflow that created it, or recreate before retrying.

How PostPeer handles it

PostPeer creates and publishes containers back-to-back. If a publish is queued past the window we requeue from scratch automatically.

Container creation failed inside Instagram.

Why it happens

The media did not match Instagram's ingestion specs (codec, resolution, aspect ratio) or Instagram returned a transient ingestion error.

How to fix

Re-encode the asset to JPEG/PNG (images) or MP4 H.264/AAC (video) at a supported aspect ratio, then retry.

Generic "unknown upload error" from Instagram.

Why it happens

Instagram's ingestion pipeline rejected the file without surfacing a specific reason — usually file corruption or an exotic edge case.

How to fix

Try a different export of the same content, ideally re-encoded from the original master.

Instagram could not fetch the media URL.

Why it happens

The URL returned a non-200, the Content-Type header was wrong, or the file was zero bytes.

How to fix

Verify the URL with curl, confirm Content-Type matches the asset (image/jpeg, video/mp4), and ensure it returns 200 without auth.

The container ID you tried to publish is gone.

Why it happens

Either the container expired (24h limit), was already published, or the ID is wrong.

How to fix

Recreate the container from the source media and publish it before the 24h window closes.

Media builder expired between create and publish.

Why it happens

Too much time passed inside the container-creation flow itself — the per-step timeout (not the 24h container timeout) was hit.

How to fix

Keep the create-then-publish flow tight; do not wait on user confirmation in the middle.

Instagram returned an unspecified error.

Why it happens

Catch-all for transient ingestion failures.

How to fix

Retry with exponential backoff. If the error persists across attempts, the underlying media or account state is the actual problem.

Image file is over 8MB.

Why it happens

Instagram's Graph API caps photo uploads at 8MB regardless of the user's plan.

How to fix

Re-export the image at lower quality or smaller dimensions, or run it through any compression tool to drop under 8MB.

Image format is not JPG or PNG.

Why it happens

Instagram's ingestion rejects HEIC, WebP, GIF, TIFF, and other formats on the Content Publishing API.

How to fix

Convert the file to JPG or PNG before submitting. Most image libraries handle this in one line.

Aspect ratio is outside the supported range (4:5 to 1.91:1).

Why it happens

Instagram only accepts aspect ratios between 4:5 (portrait) and 1.91:1 (landscape) for feed posts.

How to fix

Crop or pad the image to land in the supported range — 1:1 (square) is the safe default.

Aspect ratio is outside the supported range.

Why it happens

Same constraint as 2207009 but surfaced from a different ingestion path.

How to fix

Use 1:1, 4:5, or 1.91:1.

Image resolution exceeds 1920×1080.

Why it happens

Feed images larger than 1920px on the long edge are rejected by Instagram's validator.

How to fix

Downscale to 1920px max on the long edge.

Video format is not MP4 with H.264/AAC.

Why it happens

Instagram only ingests MP4 with H.264 video and AAC audio. HEVC, VP9, AV1, and Opus are not accepted.

How to fix

Re-encode with FFmpeg: `ffmpeg -i in.mov -c:v libx264 -c:a aac out.mp4`.

Thumbnail offset is outside the video duration.

Why it happens

You passed a `thumb_offset` larger than the video length (in milliseconds).

How to fix

Use a value between 0 and the video duration in ms. Leave it null to let Instagram pick.

Instagram could not determine the media type.

Why it happens

`media_type` was missing or mismatched the actual file format.

How to fix

Send the correct `media_type` (`IMAGE`, `VIDEO`, `REELS`, or `CAROUSEL`).

Caption is longer than 2,200 characters.

Why it happens

Instagram's caption limit is 2,200 characters including hashtags and mentions.

How to fix

Trim the caption or move overflow into a first-comment reply.

How PostPeer handles it

PostPeer counts caption length at validate-time so this never reaches the platform — you get a 400 from us with the exact overflow.

Instagram flagged the post as spam.

Why it happens

Repeated identical posts, excessive hashtags, suspicious link patterns, or copy-paste promotional language.

How to fix

Rephrase the caption, cut hashtags to under 15, and avoid posting the same text from multiple accounts in a short window.

Carousel validation failed.

Why it happens

Mixed media types, inconsistent aspect ratios, or a slide count outside the 2–10 range.

How to fix

Use 2 to 10 items, keep all items at the same aspect ratio, and avoid mixing image and video carousels.

How PostPeer handles it

PostPeer accepts up to 10 mixed items per carousel and parallelises the child-container uploads to fit inside Instagram's create-then-publish window.

Position-based product tags are not allowed on videos.

Why it happens

Instagram only supports positioned product tags on photos. Videos accept un-positioned tags only.

How to fix

Drop x/y coordinates for video posts and rely on Instagram to lay the tags out.

Position data is missing on a photo product tag.

Why it happens

Photo posts require explicit `x` and `y` (0.0–1.0) for every product tag.

How to fix

Provide normalized coordinates for each tagged product.

Product tag validation failed.

Why it happens

One of the product IDs does not exist in the connected catalog, or a coordinate is outside 0–1.

How to fix

Cross-check product IDs against the Commerce Catalog and clamp coordinates.

Too many product tags on the post.

Why it happens

Instagram caps tags at 5 per image.

How to fix

Pick the 5 most relevant products.

Instagram blocked the request as suspicious.

Why it happens

Burst posting, request volume from a single account, or unusual device/IP behavior triggered Meta's anti-abuse layer.

How to fix

Pause posting for 15–30 minutes and slow down your cadence.

The connected page hit its daily posting quota.

Why it happens

Meta limits API-driven publishing to 100 posts per page per 24h.

How to fix

Spread posts across multiple days or accounts.

How PostPeer handles it

PostPeer tracks per-account daily counts and queues overflow rather than dropping it.

Daily 100-post limit reached.

Why it happens

Same quota as `page_request_limit`, surfaced differently.

How to fix

Wait until midnight UTC for the counter to reset.

Generic Instagram service error.

Why it happens

A transient internal failure on Meta's side.

How to fix

Retry with exponential backoff — most of these resolve on the second or third attempt.

How PostPeer handles it

PostPeer retries unknown_error responses automatically before reporting failure to your webhook.