Instagram API Error Reference

Solution:

Your Instagram access token was revoked. This happens when you remove app permissions from your Instagram settings. Go to your account settings and reconnect Instagram with all required permissions.

Solution:

Your Instagram session is no longer valid. This can happen after a password change or security check. Reconnect your Instagram account to establish a new session.

Solution:

Meta rejected the access token because the underlying Instagram/Facebook user is not confirmed yet. Log into Facebook or Instagram directly, complete any pending email/phone/security confirmation steps, then reconnect the account.

Solution:

Instagram API requires a Business or Creator account. Convert your account: Go to Instagram Settings → Account → Switch to Professional Account → Choose Business.

Solution:

Instagram has restricted your account. Log into Instagram directly to see if there are any warnings or restrictions. You may need to verify your identity or appeal the restriction.

Solution:

The app doesn't have required permissions. When reconnecting, ensure you grant all permissions, especially 'instagram_content_publish' and 'instagram_basic'.

Solution:

Instagram couldn't download your media from the URL within the timeout period. Ensure your media URL is publicly accessible and the server is responding quickly. Try re-uploading.

Solution:

The media container expired before publishing. Instagram media containers expire after 24 hours. Create a new media container and publish it immediately.

Solution:

Instagram failed to create the media container. This could be a temporary issue. Wait a moment and try again. Ensure your media meets Instagram's specifications.

Solution:

An unknown error occurred during upload. Check that your media file is valid and meets Instagram's requirements. Try uploading a different file to isolate the issue.

Solution:

Instagram couldn't fetch your media from the provided URL. Verify the URL is publicly accessible, returns the correct content-type header, and the file is valid.

Solution:

The media container was not found. It may have been deleted or expired. Create a new media container and try again.

Solution:

The media builder session expired. This happens if too much time passed between creating the container and publishing. Create and publish in one flow.

Solution:

An unknown error occurred. Wait a few minutes and try again. If the issue persists, contact support with the full error details.

Solution:

Reduce your image file size. Instagram has a maximum file size of 8MB for images. Use an image compression tool to reduce the file size while maintaining quality.

Solution:

Instagram only supports JPG and PNG image formats. Convert your image to one of these formats before uploading.

Solution:

Instagram requires aspect ratios between 4:5 (portrait) and 1.91:1 (landscape). Crop or resize your image to fit within these limits.

Solution:

Your image aspect ratio is outside Instagram's allowed range. Use 1:1 (square), 4:5 (portrait), or 1.91:1 (landscape). Avoid extreme aspect ratios.

Solution:

Instagram limits image resolution to 1920x1080 pixels. Resize your image to fit within these dimensions.

Solution:

Instagram only supports MP4 video format with H.264 codec and AAC audio. Convert your video to meet these specifications.

Solution:

The thumbnail offset you specified is invalid. It must be within the video duration. Use a value between 0 and the video length in milliseconds.

Solution:

Instagram couldn't determine your media type. Ensure you're specifying the correct media_type parameter (IMAGE, VIDEO, or CAROUSEL_ALBUM).

Solution:

Instagram captions have a maximum length of 2,200 characters. Shorten your caption and try again.

Solution:

Instagram's spam detection flagged your content. Avoid repetitive posts, excessive hashtags, or spammy language. Wait a while and try posting different content.

Solution:

Instagram blocked this request, likely due to rate limiting or suspicious activity. Wait 15-30 minutes before trying again and reduce posting frequency.

Solution:

Your carousel doesn't meet Instagram's requirements. Ensure all items are the same type (all images or all videos), have consistent aspect ratios, and you have 2-10 items.

Solution:

You cannot specify product tag positions for video posts. Only image posts support positioned product tags.

Solution:

When tagging products in photos, you must specify x and y coordinates for tag positions. Provide position data for all product tags.

Solution:

One or more product tags are invalid. Verify that all product IDs exist in your catalog and position coordinates are between 0.0 and 1.0.

Solution:

Instagram limits the number of product tags per post. Reduce the number of products you're tagging (maximum is typically 5 products per image).

Solution:

You've reached Instagram's daily posting limit. Instagram allows 100 posts per day. Wait until the next day to post more content.

Solution:

Instagram enforces a 100 posts per day limit. Wait until tomorrow to post more content. Consider scheduling your posts to spread them across multiple days.

Solution:

Instagram experienced a temporary error. The system will automatically retry. If it continues failing, wait a few minutes before trying again.