Errors

01

The error body

A refused request answers with an HTTP status and this body. Branch on error_code; the message is for people and can change.

{
  "success": false,
  "message": "This API key does not have the \"publish\" scope",
  "error_code": "INSUFFICIENT_SCOPE"
}

400

The request is invalid: a missing or wrong field.

401

No key, a wrong key, or an expired one.

403

The key can’t do this: a scope or profile it doesn’t have, or a suspended workspace.

404

No such profile, post or job (or the key can’t see it).

409

A conflict: the id is in use, or a scheduled post is already publishing.

413

The file is bigger than the plan allows.

429

Too many requests, or the monthly upload limit. Wait for Retry-After.

500

Something broke on our side. Retry with the same Idempotency-Key.

02

Request error codes

INVALID_REQUEST

A field is missing or malformed.

INVALID_PLATFORM

A platform name isn’t one Reelspan posts to.

UNSUPPORTED_POST_TYPE

The platform doesn’t take this kind of post.

TITLE_REQUIRED

Text posts (and YouTube) need a title.

MEDIA_REQUIRED

The post needs a video or photos.

TOO_MANY_MEDIA_URLS

More than 100 media URLs in one request.

FILE_TOO_LARGE

Over the plan’s upload size.

UNSUPPORTED_MEDIA / EMPTY_FILE / WRONG_MEDIA_KIND

The file type isn’t accepted, the file is empty, or a photo was sent as a video.

URL_FETCH_FAILED

Reelspan couldn’t download the media URL.

MEDIA_NOT_FOUND / UPLOAD_NOT_FOUND

A media id doesn’t exist or expired.

QUEUE_FULL

The profile’s queue has no free slot in the next 30 days.

REQUEST_ID_IN_USE

Your request_id was already used.

IDEMPOTENCY_KEY_IN_USE

The first request with this key is still running.

NOTHING_TO_RETRY

No platform of this post failed.

INSUFFICIENT_SCOPE

The key lacks the scope for this call.

PROFILE_FORBIDDEN

The key is limited to other profiles.

PROFILE_NOT_FOUND

No profile with this username.

RATE_LIMITED

Too many requests this minute.

AUTH_RATE_LIMITED

Too many failed keys from this IP.

WORKSPACE_SUSPENDED

The workspace is suspended; contact support.

MAINTENANCE

Reelspan is briefly under maintenance (503 with Retry-After).

03

Platform result codes

Each platform in results succeeds or fails on its own. A failed one carries error and a lowercase error_code; a skipped one adds skipped: true and a skip_reason. The other platforms are unaffected.

reauth_required

The account’s access ended; reconnect it in the dashboard.

profile_platform_mapping_invalid

The profile has no account on this platform (skip_reason profile_platform_not_configured).

platform_disabled / platform_not_available

The platform is switched off for now.

token_error

The platform refused the account’s token.

not_supported

This platform can’t take this post as sent.

*_processing_timeout

The platform kept processing past our wait; check the post later or retry.

*_processing_failed / *_upload_failed

The platform rejected the file while processing it.

*_rate_limited

The platform’s own limit; retry later.

tiktok_duration_too_long, tiktok_privacy_unavailable

Over the account’s video length, or a privacy level it can’t use.

youtube_quotaExceeded

YouTube’s daily upload quota is used up; retry tomorrow.

x_payment_required

X’s API wants payment for the call; the X app needs more credits.

facebook_page_required

Pick a Facebook Page for the profile first.

bluesky_video_too_large

Over Bluesky’s 100 MB; send bluesky_compress=true.

internal_error

Something broke on our side; retry.

POST /api/uploadposts/posts/retry resends only what failed, keeping the platforms that went live.

04

Warnings

A result can succeed and still carry warnings: a caption shortened to fit, links removed from an X post, or a first comment the platform refused. The post is live; the warning says what changed.

05

Next steps