Errors

There are two kinds of error, and a client should handle both:

1. The request is refused. You get an HTTP error status and an error body. Nothing was posted.
2. The request is accepted, but a network fails. The request succeeds, and that network's entry in results has success: false with an error_code. The other networks are not affected.

The error body

A refused request answers with this JSON:

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

• Branch on error_code. The message is written for people and can change.
• Request error codes are UPPER_CASE; network result codes are lower_case.
• Some errors add fields: usage on a monthly limit, platform when one network's rule refused the request, invalid_platforms when no requested network can be used, api_url on a 421.
• A few errors have no error_code, only message (for example an unknown route, an invalid timezone or a key that is wrong). Fall back on the HTTP status.
• Server errors use error instead of message: { "success": false, "error": "Internal server error" }.

HTTP statuses

Request error codes

Authentication and access

Posting

A request that would go over the monthly upload limit is refused with 429 and the current usage (count, limit, last_reset) in the body. When none of the requested networks can be used (none connected, all needing reconnection), the request is refused with 400 and invalid_platforms, giving the reason for each.

Media

Scheduling, retries and approvals

Profiles, accounts and connecting

When connecting with credentials (POST /v1/accounts/{platform}), a refusal from the network comes back as 400 with the network's code in upper case, such as INVALID_TOKEN, INVALID_CREDENTIALS, INVALID_WEBHOOK or INVALID_SERVER, or 403 PLATFORM_DISABLED.

A browser connect flow (OAuth or the hosted connect page) can't answer with JSON, so it sends the person back to your redirect with connect_status=error, an error_code (INVALID_STATE for an expired link, ACCESS_DENIED, CONNECTION_FAILED, NOT_SUPPORTED, RATE_LIMITED, WORKSPACE_SUSPENDED or PROFILE_NOT_FOUND) and usually an error_description. A person who cancels comes back with connect_status=cancelled.

AI captions

Network result codes

Each network in results (and in Post status and upload_completed webhooks) has its own outcome:

{
  "tiktok": { "success": true, "url": "https://www.tiktok.com/@mybrand/video/7441…", "post_id": "7441…" },
  "instagram": { "success": false, "error": "Instagram could not process the video: ERROR", "error_code": "instagram_processing_failed" },
  "x": { "success": false, "skipped": true, "skip_reason": "profile_platform_not_configured", "error": "Profile my-brand has no X account configured", "error_code": "profile_platform_mapping_invalid" }
}

A failed network has error (for people) and error_code (for code). A network that was never tried also has skipped: true and a skip_reason. Failures that were temporary on the network's side (its 5xx answers, its rate limits, timeouts) are retried automatically, up to four attempts in all, before the result is final.

Many codes are built from what the network said: tiktok_<TikTok's code>, youtube_<YouTube's reason>. Treat any code you don't know by its prefix and the error text.

Any network

TikTok

YouTube

Instagram and Facebook

X, Threads, LinkedIn, Pinterest, Bluesky

Other networks

For symptoms and fixes, see Troubleshooting.

Warnings

A network can succeed and still carry warnings: text cut to fit, links removed from an X post, a long post turned into a thread, extra photos left out, or a first comment the network refused. The post is live; the warning says what changed.