Troubleshooting

Fix common Reelspan problems by symptom: reconnecting accounts, TikTok privacy, Instagram processing, YouTube quota, large files and rate limits.

Find the symptom, check the error_code in the response or in that network's result, and apply the fix. Every code is listed on Errors.

Most network failures can be sent again without uploading the media: POST /v1/posts/retry with the request_id resends only the networks that failed. See Retry.

Requests refused

401: "Invalid API key" or "API key expired"

Cause: the Authorization header is missing, misspelled, or holds a revoked or expired key. Fix: send Authorization: Bearer rs_live_… (or rs_test_…) exactly; no quotes, no Apikey prefix. Check the key in the dashboard under API keys and create a new one if it was revoked or expired. After 10 failed attempts in 5 minutes your IP address is refused for up to 5 minutes (AUTH_RATE_LIMITED), so fix the key before retrying.

421 `USE_API_HOST`

Cause: the request went to app.reelspan.com, the dashboard's address. Fix: use https://api.reelspan.com/v1, as given in the response's api_url.

403 `INSUFFICIENT_SCOPE` or `PROFILE_FORBIDDEN`

Cause: the key was created with limited scopes, or limited to some profiles. Fix: use a key with the scope named in the message (publish, read, profiles, analytics, webhooks), or one allowed on that profile. See Authentication.

404 "User not found" (`PROFILE_NOT_FOUND`)

Cause: user must be the profile's username in your workspace, not a display name or a network handle. Fix: list your profiles with GET /v1/profiles and use the username.

400 "None of the requested platforms are valid for profile…"

Cause: every network you asked for is unusable on this profile: not connected, or needing reconnection. The body's invalid_platforms gives the reason for each. Fix: connect the accounts to the profile (see Connecting accounts), or reconnect them.

400 `INVALID_REQUEST` naming a network

Cause: a network's required field is missing: YouTube needs a title (title or youtube_title), Pinterest a pinterest_board_id, Reddit a reddit_subreddit. Fix: add the field. Pinterest boards are listed by GET /v1/pinterest/boards.

400 `UNSUPPORTED_POST_TYPE`

Cause: the network has no API for this kind of post: text-only to Instagram, TikTok or Pinterest; video to Google Business; a document anywhere but LinkedIn. Fix: drop that network from this request.

413 `FILE_TOO_LARGE`, or the upload breaks off

Cause: the video is over your plan's size, a photo over 20 MB or a PDF over 100 MB; or a single request carried more than 100 MB. Fix: for big files use a direct upload, or let the SDK do it (it switches at 90 MB). A video over your plan's limit needs a smaller file or a bigger plan. See Large files.

400 `URL_FETCH_FAILED`

Cause: Reelspan couldn't download the media URL: it isn't https://, isn't public, needs a sign-in, points to a private address, or redirects more than three times. Fix: open the URL in a private browser window; it must download the file directly. For Google Drive, share the file with "Anyone with the link".

429 `RATE_LIMITED`

Cause: too many requests in the current minute or 10 minutes for your plan, often from polling. Fix: wait for Retry-After, poll every 5 seconds or more, or use webhooks. See Rate limits.

429 with `usage`, or `USAGE_LIMIT`

Cause: the Free plan's 15 uploads this month are used (one per network per post). Fix: wait for the 1st (UTC), or upgrade. Test posts with an rs_test_ key don't count.

409 `IDEMPOTENCY_KEY_IN_USE`

Cause: you retried while the first request with the same key was still being received. Fix: wait a few seconds and send it again with the same key. See Retrying safely.

409 `REQUEST_ID_IN_USE`

Cause: the request_id you chose was used before. Fix: read that request's status instead of posting again, or choose a new id for a new post.

409 `scheduled_post_in_progress`

Cause: the scheduled post is publishing or due within a minute. Fix: wait for it to finish, then retry or delete the posts on the network if needed.

A network failed

`reauth_required` or `token_error`

Cause: the network no longer accepts the account's access: the password changed, access was revoked, the token expired, or a permission was removed. Reelspan marks the account for reconnection and sends a social_account_reauth_required webhook. Fix: reconnect the account in the dashboard (or send your client a new connect link), then retry the post.

`profile_platform_mapping_invalid` (skipped)

Cause: the profile has no active account on that network, at the time the post ran. Fix: connect one. For scheduled posts, connect it before the post's time.

`tiktok_privacy_unavailable`

Cause: the privacy_level you sent isn't one this TikTok account may use. TikTok decides the levels per account. Fix: use one of the levels listed in the message, or read the account's options first with GET /v1/tiktok/creator-info. Leave privacy_level out and Reelspan picks PUBLIC_TO_EVERYONE when allowed, else the account's first option.

A TikTok post went out as private ("Only me")

Cause: until Reelspan's app passes TikTok's audit, TikTok accepts direct posts only as private. When TikTok refuses a public post for this reason, Reelspan posts it as private instead and adds a warning to the result. If even that is refused, the result fails with tiktok_unaudited_client_can_only_post_to_private_accounts. Fix: make the post public in the TikTok app; or make the TikTok account itself private (Settings → Privacy) before posting; or post with post_mode=MEDIA_UPLOAD to send the video to the TikTok inbox and finish it in the app.

`tiktok_duration_too_long`

Cause: the video is longer than TikTok allows this account. Fix: trim it to the length in the message.

`tiktok_spam_risk_too_many_posts` or `tiktok_reached_active_user_cap`

Cause: a TikTok daily limit: posts for this account, or accounts posting through Reelspan's app. Fix: retry the next day. See Network posting limits.

`instagram_processing_timeout`

Cause: Instagram was still processing the video when Reelspan stopped waiting. It may still appear on the account. Fix: check the account first. If the post isn't there after a few minutes, retry. Very large or long videos process slowest.

`instagram_processing_failed`, `facebook_processing_failed`

Cause: the network couldn't process the file: an unusual codec, shape or length for that network. Fix: export as H.264 with AAC audio in an MP4, in a shape the network takes (9:16 for Reels and Stories), and retry. See Video requirements.

`facebook_page_required` or `facebook_page_not_connected`

Cause: no Facebook Page is chosen for the profile, or the Page wasn't shared with Reelspan when connecting. Fix: reconnect Facebook and select the Page. GET /v1/facebook/pages lists the Pages Reelspan can post to.

`meta_permission_denied`

Cause: a permission Reelspan needs was removed from the Facebook or Instagram connection. Fix: reconnect and accept every permission.

`youtube_quotaExceeded` or `youtube_uploadLimitExceeded`

Cause: YouTube's daily upload limit was reached. Fix: retry the next day. See Network posting limits.

`youtube_youtubeSignupRequired`

Cause: the Google account has no YouTube channel. Fix: create a channel on YouTube, then reconnect.

`x_payment_required`

Cause: X refused the call for billing reasons on the API side. Fix: retry later; if it keeps happening, contact support with the request_id.

Links missing from an X post

Cause: Reelspan removes links from X posts by default, with a warning in the result. Fix: send x_keep_links=true. Your plan includes a monthly number of X posts with links. See Character limits.

`bluesky_video_too_large`

Cause: Bluesky takes videos up to 100 MB. Fix: send bluesky_compress=true and Reelspan compresses it for Bluesky, or upload a smaller file.

`bluesky_email_unconfirmed`

Cause: Bluesky needs the account's email confirmed before it takes video. Fix: confirm the email in Bluesky's settings and retry.

`file_too_large` on Telegram, Discord or Mastodon

Cause: the network's own file limit: Telegram 50 MB, Discord 10 MB, Mastodon 99 MB. Fix: send a smaller file to that network in a separate request.

`bot_not_admin` (Telegram)

Cause: your bot isn't an admin of the channel or group with permission to post. Fix: add the bot as an admin who can post messages, then retry.

A `*_processing_timeout` code

Cause: the network was still processing the media when Reelspan stopped waiting. Fix: check whether the post appeared before retrying, so it isn't posted twice.