Common Errors

This guide covers the most common errors you might encounter when using Upload-Post and how to resolve them. Errors are organized by category to help you quickly find solutions.

Session Expired

Session and authentication errors occur when the connection between Upload-Post and your social media account has been broken. This is usually easy to fix by reconnecting your account.

Common Session Errors

Error Message	Platform	Solution
error_code: "reddit_unavailable" (HTTP 503)	Reddit	Reddit posting, OAuth, and comments are currently unavailable. Do not send platform[]=reddit.
"Your [Platform] session has expired"	All	Reconnect your account
"Token expired and refresh failed"	All	Reconnect your account
"The session has been invalidated because the user changed their password"	Facebook/Instagram	Reconnect after password change
"Error validating access token"	Facebook/Instagram	Verify permissions and reconnect
"Your X session has expired and could not be refreshed"	X (Twitter)	Reconnect your X account
"User has not authorized application"	Various	Grant permissions and reconnect
"Unauthorized"	Various	Reconnect your account

How to Fix Session Errors

1. Go to Manage Users

2. Find the affected account - Look for accounts with warning indicators

3. Disconnect the account - Click the disconnect/remove button next to the account

4. Reconnect the account - Click "Connect" and complete the authorization flow

5. Grant all permissions - Make sure to approve all requested permissions during reconnection

tip

If you recently changed your password on a social media platform, you'll need to reconnect that account in Upload-Post.

Meta checkpoint ("log in to instagram.com and follow the instructions")

Instagram, Facebook and Threads sometimes answer a publish with error_code: "account_checkpoint_required" — Graph API error 190 / subcode 459, "You cannot access the app till you log in to www.instagram.com and follow the instructions given". Meta is asking the account owner to clear a security prompt on the platform itself; the token is not the problem and reconnecting alone does not clear it.

Because every attempt fails until the prompt is cleared, Upload-Post marks the account as needing reauthentication on the first checkpoint (it used to take five failures over five hours). From then on:

• New posts for that account are rejected at precheck with error_code: "account_reauth_required", failure_stage: "precheck"; no credit is consumed and nothing is sent to Meta.
• The account owner receives the reconnection email once.
• Once a day Upload-Post probes flagged Instagram and Threads accounts. If Meta has stopped returning the checkpoint (the owner logged in and completed the prompt), the flag is cleared automatically and posting resumes with no further action. Reconnecting the account from Manage Users also clears it immediately.

---

Account Blocked

These errors occur when there's an issue with your account on the social media platform itself. Upload-Post cannot fix these - you need to resolve them directly on the platform.

Common Account Status Errors

Error Message	Platform	What It Means
"Sessions for the user are not allowed because the user is not a confirmed user"	Facebook	Account needs verification
"The YouTube account of the authenticated user is suspended"	YouTube	Account suspended by YouTube
"Your account is temporarily locked"	X (Twitter)	X has locked your account
"The Instagram account is restricted or inactive"	Instagram	Instagram has restricted your account
"Action suspected as spam. Activity is restricted"	Instagram	Spam detection triggered
"The user used for authentication is suspended"	Various	Account suspended on platform

How to Fix Account Blocked Errors

These issues must be resolved directly on the social media platform:

Facebook/Instagram Account Not Confirmed

1. Go to facebook.com and log in
2. Check for any verification prompts or security notices
3. Go to Settings & Privacy > Settings > Personal Details
4. Verify your email and phone number are confirmed
5. Visit Facebook Account Quality to check for restrictions
6. After resolving issues, reconnect in Upload-Post

X (Twitter) Account Locked

1. Go to twitter.com or x.com and log in
2. Follow the prompts to unlock your account (may require phone verification)
3. Once unlocked, reconnect in Upload-Post

YouTube Account Suspended

1. Go to YouTube and sign in
2. Check the YouTube Help Center for suspension appeals
3. Follow YouTube's process to restore your account

Instagram Restricted

1. Open the Instagram app and log in
2. Look for any notification banners or prompts
3. Follow Instagram's instructions to verify your identity
4. After restrictions are lifted, reconnect in Upload-Post

Temporary restrictions ("Action suspected as spam. Activity is restricted")

Instagram answers with this error (Graph API error 4 / subcode 2207051) when its spam detector flags an account — typically after many feed posts in a short time from a newly connected account. It is a temporary block on Instagram's side, usually 24–48 hours; your access token is still valid and Stories keep working.

When Upload-Post receives it:

• Your Instagram account stays connected to the profile. Reconnecting does not lift the block, and every retry can extend it.
• Upload-Post pauses feed posts for that account for 24 hours and rejects them at precheck with error_code: "account_restricted", failure_stage: "precheck" and a restricted_until timestamp. Upload credits are not consumed for these rejections.
• Stories are not paused.
• You receive one email explaining the pause.

To resolve it: open the Instagram app, complete any "review your account" prompt, wait 24–48 hours, then resume at a lower cadence (a few feed posts per day, varied captions). If you know the restriction has already been lifted, reconnecting the account in Upload-Post ends the pause early.

Other paused accounts (account_restricted at precheck)

The same pause mechanism is used for every platform verdict that is known to keep failing until something on the platform changes. Instead of failing post after post (and burning credits and platform quota), Upload-Post pauses the account for a window that matches the platform's own reset and rejects new posts at precheck with error_code: "account_restricted", failure_stage: "precheck", restriction_reason, restricted_until and retry_after_seconds. Credits are refunded, the account stays connected, and reconnecting it from Manage Users ends the pause early.

restriction_reason	Platform	What triggered it	Pause
spam_restricted	Instagram	"Action suspected as spam. Activity is restricted"	24 h
daily_upload_limit	YouTube	"This channel has reached the number of videos it may upload today" (a per-channel limit set by YouTube, normally reset around midnight Pacific Time)	2 h, then retried
rate_limited	Facebook	"We limit how often you can post, comment or do other things in a given amount of time" — only when the Facebook login manages a single Page (the limit is per Page)	1 h
publish_limit	Instagram	"Daily publishing limit reached" (Instagram's 24-hour rolling API publishing limit)	30 min
identity_confirmation	Facebook	"Confirm your identity before you can publish as this Page" — only when the Facebook login manages a single Page (the verdict is per Page)	24 h (email sent)
permission_denied	YouTube	"You do not have permission to perform this action"	24 h (email sent)
spam_risk_*	TikTok	TikTok anti-spam verdicts, see TikTok Spam-Risk Errors	1 h – 7 days

Instagram Stories are exempt from the spam_restricted pause (Meta's spam block is feed-only and stories keep working), but not from the quota pauses (publish_limit, rate_limited, daily_upload_limit), where stories count against the same allowance.

Throughput limits (daily_upload_limit, rate_limited, publish_limit) clear by themselves and do not send an email; the pause is only visible in the upload response, /api/uploadposts/status and the account badge in the dashboard. The windows are deliberately shorter than the platform's nominal reset: the limits are partly rolling, so a post after the pause often goes through, and if the platform refuses again the account is simply paused again. Verdicts that need the owner to act (identity_confirmation, permission_denied) send one email. Don't re-queue a paused account before restricted_until: the request will not reach the platform anyway.

warning

Upload-Post cannot bypass platform restrictions. You must resolve these issues directly with the social media platform before reconnecting.

---

Configuration & Permissions

These errors occur when your account is connected but requires additional configuration or permissions.

Common Configuration Errors

Error Message	Platform	Solution
"No Facebook Pages found for your account"	Facebook	Connect a Facebook Page (personal profiles not supported)
"Multiple Facebook Pages found. Please select a Page"	Facebook	Select which Page to post to
"Facebook Page ID is required for text posts"	Facebook	Configure your profile to select a Page
"Couldn't get a Facebook Page access token for Page ID..."	Facebook	Reconnect with proper Page permissions
"Pinterest account not found or not configured"	Pinterest	Configure Pinterest in your profile
"Board not found"	Pinterest	Select a valid Pinterest board
"You are not permitted to access that resource"	Various	Check your role/permissions on the account
"This site doesn't allow you to save Pins"	Pinterest	The target site blocks Pinterest pins
"quote_tweet_id cannot be used when uploading media to X. Remove it and retry."	X (Twitter)	Quote tweets and media are mutually exclusive — drop quote_tweet_id or remove the media
"X rejected this reply (403)... not permitted to reply to this author on X's Pay-Per-Use tier"	X (Twitter)	Reply to an author the account has engaged with (this is a platform restriction, not a session error — reconnecting won't help)
error_code: "tiktok_reconnect_required"	TikTok	The TikTok connection cannot serve this endpoint. Reconnect the account
error_code: "platform_not_supported"	Various	That network cannot answer this question yet. What it means

TikTok: tiktok_reconnect_required

HTTP 400. The profile has a working TikTok connection — it publishes fine — but that connection does not carry what the endpoint you called needs. TikTok decides an account's permissions at the moment it is connected, so an account connected a while ago simply never got them.

{
  "success": false,
  "message": "Profile 'your_profile' has no TikTok connection that supports this endpoint. Reconnect your TikTok account from Manage Users.",
  "error_code": "tiktok_reconnect_required"
}

Which endpoints return it

Endpoint	Capability needed
Comments with platform=tiktok (list / create / delete)	comments
Comment replies (comment_id) and hide / like / pin	comments
Suggestions with type=keywords	trend_search
Audience Insights (with its category benchmark), Suggestions with type=hashtags, the TikTok per-post breakdown in Analytics	profile_analytics
Get TikTok Settings, Music, Locations	a current connection

How to fix it

1. Read the profile's capabilities from GET /api/uploadposts/users to see what the connection actually has.
2. Have the account owner reconnect TikTok from Manage Users, or send them through a white-label connect link.
3. Nothing in your integration changes — same endpoints, same field names. The capability appears in capabilities once the account is back.

Do not confuse it with a session error. reauth_required / HTTP 409 means the token expired; tiktok_reconnect_required means the token is fine and the permission was never granted. Both are fixed by reconnecting, but only the first one blocks publishing.

Uploading is never blocked by this. Sending an optional field the connection does not support still publishes the post and returns a warnings array naming what was ignored — including a first_comment on TikTok, which is skipped with a warning instead of failing the publish.

platform_not_supported

HTTP 400. Upload-Post's API is one endpoint per question, with a platform telling it which network to ask — never one URL per network. When a network cannot answer that question yet, you get this code instead of an empty 200, and the message names the ones that can:

{
  "success": false,
  "message": "'instagram' does not support audience insights yet. Supported: tiktok.",
  "error_code": "platform_not_supported"
}

It is not a misconfiguration and reconnecting the account will not fix it: the integration for that network simply is not built yet. Branch on the error_code, not on a hard-coded list of platforms — when the network starts answering, the same call you already make begins returning data, with no change on your side.

Endpoints that can answer it today: GET /api/uploadposts/audience, GET /api/uploadposts/suggestions and POST /api/uploadposts/comments/action (where the field is called error rather than message).

How to Fix Configuration Errors

Facebook Page Issues

Facebook requires you to post to a Facebook Page, not a personal profile. The Facebook API does not support posting to personal profiles.

1. Create a Facebook Page (if you don't have one):

   • Go to Create a Page
   • Follow the setup wizard

2. Connect your Page to Upload-Post:

   • Go to Manage Users
   • Disconnect your Facebook account
   • Reconnect and select the Page you want to post to
   • Make sure you have Admin or Editor role on the Page

3. Select the correct Page in your profile:

   • Go to your Upload-Post profile settings
   • Select the Facebook Page from the dropdown

Required Permissions

To post to a Facebook Page, you need:

• Admin or Editor role on the Page
• Grant "pages_manage_posts" permission during connection
• Grant "pages_read_engagement" permission

Pinterest Board Issues

1. Make sure you have at least one board in your Pinterest account
2. Go to your Upload-Post profile and select the correct board
3. If the board was recently created, try disconnecting and reconnecting Pinterest

---

Content Format

These errors occur when your media doesn't meet the platform's requirements for size, format, or aspect ratio.

Common Content Errors

Error Message	Platform	Solution
"Unsupported image size"	Various	Use supported dimensions
"Invalid image aspect ratio"	Instagram	Use ratio between 4:5 and 1.91:1
"Video longer than 2 minutes"	X (Twitter)	Shorten video or upgrade X account
"TikTok rejected the media format"	TikTok	Use MP4/MOV format
"One or more tags are invalid"	Various	Remove special characters from tags
"Your post must contain post flair"	Reddit	Add required flair to your post
"Media could not be fetched from the provided URL"	Various	Use a publicly accessible URL
"Downloaded file is too small"	Various	Check URL points to valid media
"Collaborator usernames are invalid"	Instagram	Use valid public usernames without @
"Your title is too long for LinkedIn"	LinkedIn	See LinkedIn media title limit below

LinkedIn: title too long on video and document posts

LinkedIn caps the media title of a video or document post at 400 characters and rejects the whole post above that. Two things make a title that looks short go over:

• Line breaks travel as CRLF. A \n in a form field reaches the API as \r\n, two characters. A title with 4 line breaks counted as 396 locally arrives as 400.
• Emoji count twice. LinkedIn measures in UTF-16 code units, so 🌍 is two characters, not one.

Upload-Post now trims an over-long title to 400 characters and adds a warnings entry to the response rather than failing the post. To keep the title intact, put the long text in description (the post body), which has a much larger limit, and send a short title.

See Character Limits for every platform's caps.

Media Requirements by Platform

Platform	Image Format	Max Image Size	Video Format	Max Video Duration
Instagram	JPG, PNG	8 MB	MP4, MOV	60 min (Feed), 90 sec (Reels)
Facebook	JPG, PNG, GIF	10 MB	MP4, MOV	240 min
TikTok	-	-	MP4, MOV	10 min
X (Twitter)	JPG, PNG, GIF	5 MB	MP4	2 min 20 sec*
LinkedIn	JPG, PNG	8 MB	MP4	10 min
YouTube	-	-	MP4, MOV, AVI	12 hours
Pinterest	JPG, PNG	32 MB	MP4, MOV	15 min

*X Premium users may have longer video limits

Instagram Aspect Ratio Guidelines

• Square: 1:1
• Portrait: 4:5 (recommended for Feed)
• Landscape: 1.91:1
• Stories/Reels: 9:16

Images outside the 4:5 to 1.91:1 range will be rejected.

tip

For best results, use 1080x1350 pixels (4:5 ratio) for Instagram feed posts.

Fixing Media URL Issues

If you're getting "Media could not be fetched" errors:

1. Check the URL is publicly accessible - Open it in an incognito browser window
2. Don't use private/restricted URLs - Google Drive links must be set to "Anyone with the link"
3. Use direct file URLs - The URL should end with a file extension like .jpg or .mp4
4. Check file size - Very small files (< 1KB) often indicate a broken link

---

Rate Limits

These errors occur when you've hit posting limits or the platform is experiencing temporary issues.

Common Rate Limit Errors

Error Message	Platform	Solution
"This YouTube channel has reached the number of videos it may upload today" (youtube_channel_daily_limit)	YouTube	Per-channel limit set by YouTube, normally reset around midnight Pacific Time. Upload-Post pauses the channel for 2 h and retries.
"Service Unavailable (503)"	Various	Retry in a few minutes
"Temporary issue. We retried 4 times but it still failed"	Instagram	Platform issue - retry later
"Fatal" / "Unexpected error"	Various	Platform issue - retry later
"Rate limit reached"	Various	Wait before making more requests

Platform Daily Limits

Platform	Daily Posting Limit
Instagram	~50 posts per day
TikTok	15-20 videos per day
LinkedIn	~150 posts per day
Pinterest	25 pins per day
Reddit	Varies by subreddit
YouTube	30 videos per day

TikTok Spam-Risk Errors

TikTok enforces per-account anti-spam caps on API posting. These are rolling 24-hour limits on your TikTok account, not an Upload-Post restriction — no retry or reconnect can lift them early.

Error	What it means	How to fix
spam_risk_too_many_pending_share	Your TikTok account has reached the cap of 5 unpublished (pending) inbox drafts in 24 hours. This happens when videos are sent to the TikTok inbox but never published from the app.	Open the TikTok app and publish or discard your pending drafts (Inbox → System notifications), then wait for the 24h window to roll.
spam_risk_too_many_posts	Your TikTok account reached its daily API posting cap (typically ~15 posts per day per account; the exact number varies per creator).	Wait for the rolling 24h window. Spread posts across the day or across accounts.
spam_risk_user_banned_from_posting	TikTok has banned this account from posting via API.	Contact TikTok support from the affected account.

Upload-Post parks restricted accounts. After one of these verdicts, Upload-Post stops sending that TikTok account to TikTok for a while and answers new uploads immediately with error_code: "account_restricted", failure_stage: "precheck", restriction_reason, restricted_until and retry_after_seconds (the credit is refunded). Windows: spam_risk_user_banned_from_posting → 7 days, spam_risk_too_many_posts → 1 hour (TikTok's limit is rolling, so we only pause long enough to stop retries). Post-level verdicts (spam_risk_text, spam_risk) and the inbox-draft backlog (spam_risk_too_many_pending_share) never park the account — fix the text / publish the drafts and retry. The account owner also receives an email when the account is parked, and reconnecting the TikTok account in Upload-Post clears the pause (for example after TikTok support lifted the restriction). Don't re-queue a parked account before restricted_until: the request will not reach TikTok anyway.

Official TikTok references: Content Sharing Guidelines · Content Posting API — Upload Video

Inbox mode and pending drafts

If your posts are being delivered to the TikTok inbox (for example while the daily active-user cap fallback is active), remember to publish them from the app — 5 unpublished drafts will block further uploads for 24h with spam_risk_too_many_pending_share.

Pinterest video Pins: "Sorry! This site doesn't allow you to save Pins"

Despite the wording, this answer (Pinterest error code: 1) has nothing to do with the Pin's link: in production it only ever happens on video Pins, right after the uploaded video's processing status turns succeeded, and the same account usually publishes fine minutes later. Upload-Post treats it as a transient Pinterest refusal and retries the identical Pin twice (after 15 s and 30 s) before reporting the error; nothing about the Pin is changed. If all attempts are refused, retry the request a few minutes later.

Bluesky Requirements

Error	What it means	How to fix
"Bluesky requires a verified email before uploading videos" (unconfirmed_email)	Bluesky-hosted accounts must have a verified email before the video service accepts uploads. Only the account owner can verify it.	In the Bluesky app: Settings → Account → Email → Verify, then retry the upload.
"Bluesky allows at most 4 images per post; the first 4 of N were published"	The AT Protocol schema hard-limits image posts to 4 images. Upload-Post publishes the first four and reports the rest in the response's warnings array (success stays true).	Send 4 images or fewer if you need to choose which ones are published.

Official Bluesky references: Video uploads · Creating posts

Handling Rate Limits

1. Wait and retry - Most limits reset at midnight UTC
2. Spread posts throughout the day - Avoid posting many items at once
3. Use scheduling - Schedule posts to spread them out automatically
4. Check your usage - View your posting history to track activity

Automatic Rescheduling

When you hit a daily limit, Upload-Post may automatically reschedule your post for the next day. Check your scheduled posts to confirm.

---

Getting Help

If your error isn't listed here or you need additional assistance:

1. Check our FAQ for general questions
2. Review our API Error Handling Guide for technical details
3. Contact support at info@upload-post.com

When contacting support, please include:

• The exact error message you received
• The platform you were posting to
• The type of content (text, photo, video)
• When the error occurred

---

Platform Help Centers

If you need to resolve issues directly with a social media platform:

• Facebook Help Center
• Instagram Help Center
• TikTok Support
• YouTube Help
• X (Twitter) Help
• LinkedIn Help
• Pinterest Help
• Reddit Help