Skip to main content
Sign Up
All platforms

TikTok Content Posting API

TikTok API Errors

The TikTok Content Posting API's full error surface — auth, spam detection, video format, app-status, and publishing constraints.

TikTok has the strictest validation of any major social API: codec, frame rate, resolution, duration, creator privacy options, and audited-app status all gate publishing.

PostPeer TikTok APIView Docs
Authentication3Spam6Video format6Media3Rate limit2App status3Server2

Authentication

3 errors in this category

access_token_invalidAuthentication

TikTok rejected the access token.

Why it happens
TikTok tokens expire 24 hours after issue. If the refresh token is also gone or stale, the integration is bricked.
How to fix
Reconnect the TikTok account to mint a new token pair.
How PostPeer handles it
PostPeer refreshes TikTok tokens preemptively and persists the rotated refresh token immediately, since TikTok refresh tokens are single-use.
scope_not_authorizedAuthentication

Required scope was not granted during OAuth.

Why it happens
TikTok's consent screen lets users opt out of individual scopes. Posting requires `video.upload` (or `video.publish`) and `user.info.basic`.
How to fix
Run the connect flow again and explicitly approve every requested scope.
scope_permission_missedAuthentication

Operation needs a scope the token does not have.

Why it happens
Same as `scope_not_authorized` but raised at call time rather than at token introspection.
How to fix
Reconnect with the additional scope requested in the OAuth URL.

Spam

6 errors in this category

spam_risk_user_banned_from_postingSpam

TikTok banned the account from publishing.

Why it happens
Repeated community-guideline violations or rapid automated posting.
How to fix
Log into the TikTok app, review any warnings, and appeal the restriction if you believe it was applied in error.
spam_risk_textSpam

TikTok detected spam in the caption text.

Why it happens
Repetitive phrasing, excessive links, or promotional copy patterns.
How to fix
Rewrite the caption with original phrasing.
spam_risk_too_many_postsSpam

Account hit its 24-hour posting cap.

Why it happens
TikTok limits how many posts a single account can publish per day via the API.
How to fix
Wait 24 hours or spread posts across multiple accounts.
spam_risk_too_many_pending_shareSpam

Too many shares are queued in TikTok's pending state.

Why it happens
TikTok allows max 5 pending API shares per user per 24h window.
How to fix
Wait for pending shares to publish or be reviewed before queueing more.
spam_riskSpam

Generic spam-detection match.

Why it happens
Content fingerprint matched something already flagged by TikTok.
How to fix
Re-shoot or significantly edit the video; trivial changes will still match.
reached_active_user_capSpam

Your TikTok app hit its daily active-user quota.

Why it happens
Unaudited apps have a hard cap on daily distinct users they can serve.
How to fix
Submit your app for TikTok review to lift the cap, or wait 24h.

Video format

6 errors in this category

file_format_check_failedVideo format

TikTok did not accept the video container/codec.

Why it happens
Anything outside MP4 (H.264) or WebM is rejected.
How to fix
Re-encode to MP4 with H.264 video and AAC audio.
duration_check_failedVideo format

Video duration is outside TikTok's accepted range.

Why it happens
TikTok accepts 3 seconds to 10 minutes for API uploads.
How to fix
Trim shorter clips up to 3s, or cut long ones under 10 min.
frame_rate_check_failedVideo format

Frame rate is outside 23–60 fps.

Why it happens
TikTok's ingestion enforces a frame rate band.
How to fix
Re-encode at 30 fps for safe compatibility.
picture_size_check_failedVideo format

Resolution is below 720p.

Why it happens
TikTok rejects sub-HD video on the Content Posting API.
How to fix
Re-export from a 720p+ source.
video durationVideo format

Video is longer than TikTok's 10-minute API max.

Why it happens
Same as `duration_check_failed`, raised in a different layer.
How to fix
Trim or split into a multi-part series.
file sizeVideo format

Video file exceeds ~287MB upload cap.

Why it happens
TikTok's pull-from-URL endpoint enforces a hard byte cap.
How to fix
Re-encode with a lower bitrate or shorter duration.

Media

3 errors in this category

video_pull_failedMedia

TikTok could not fetch the video URL.

Why it happens
URL was unreachable, returned a non-200, had the wrong Content-Type, or was redirected.
How to fix
Serve the file from a public URL returning `video/mp4` and no redirects.
How PostPeer handles it
PostPeer hosts uploaded media on our CDN to eliminate this entirely.
photo_pull_failedMedia

TikTok could not fetch the image URL.

Why it happens
Same shape as `video_pull_failed` for photo posts.
How to fix
Use a public URL returning `image/jpeg` or `image/png`.
invalid_file_uploadMedia

File failed TikTok's upload validation.

Why it happens
Combination of size, codec, or format mismatch.
How to fix
Cross-check the file against TikTok's Content Posting specs and re-export.

Rate limit

2 errors in this category

rate_limit_exceededHTTP 429Rate limit

Too many API requests in a short window.

Why it happens
TikTok limits both per-app and per-user request rates.
How to fix
Back off exponentially. PostPeer respects the `Retry-After` header automatically.
too many requestsHTTP 429Rate limit

Generic 429 from TikTok's gateway.

Why it happens
Burst of requests from the same app or user.
How to fix
Add jitter to your retry logic.

App status

3 errors in this category

unaudited_client_can_only_post_to_private_accountsApp status

Your TikTok app has not been audited yet.

Why it happens
Unaudited apps can only post in private (self-only) mode regardless of the user-requested privacy level.
How to fix
Submit your app for TikTok's Content Posting audit to unlock public posting.
url_ownership_unverifiedApp status

You tried to attach a domain you have not verified.

Why it happens
TikTok requires domain verification for any external URL embedded in a post.
How to fix
Verify ownership in TikTok's developer console via DNS or `.well-known` proof.
privacy_level_option_mismatchApp status

Requested privacy level is not allowed for this app/account.

Why it happens
The creator's allowed `privacy_level_options` (from /v2/post/publish/creator_info/) did not include the value you sent.
How to fix
Pull creator info first and pick a value from the returned `privacyLevelOptions` array.
How PostPeer handles it
PostPeer exposes `get_tiktok_creator_info` so your UI can render only valid options. The publish layer also revalidates against the creator response.

Server

2 errors in this category

internalHTTP 500Server

TikTok server-side failure.

Why it happens
Transient outage or partial dependency failure.
How to fix
Retry with exponential backoff.
invalid_paramsHTTP 400Server

A required parameter is missing or malformed.

Why it happens
API contract was not followed — usually a missing `post_info` field or wrong enum value.
How to fix
Diff your request body against TikTok's OpenAPI spec for the endpoint.

Quick reference

All 25 TikTok errors in one table — Ctrl/Cmd-F to find yours.

CodeWhat it means
access_token_invalidTikTok rejected the access token.
scope_not_authorizedRequired scope was not granted during OAuth.
scope_permission_missedOperation needs a scope the token does not have.
spam_risk_user_banned_from_postingTikTok banned the account from publishing.
spam_risk_textTikTok detected spam in the caption text.
spam_risk_too_many_postsAccount hit its 24-hour posting cap.
spam_risk_too_many_pending_shareToo many shares are queued in TikTok's pending state.
spam_riskGeneric spam-detection match.
reached_active_user_capYour TikTok app hit its daily active-user quota.
file_format_check_failedTikTok did not accept the video container/codec.
duration_check_failedVideo duration is outside TikTok's accepted range.
frame_rate_check_failedFrame rate is outside 23–60 fps.
picture_size_check_failedResolution is below 720p.
video durationVideo is longer than TikTok's 10-minute API max.
file sizeVideo file exceeds ~287MB upload cap.
video_pull_failedTikTok could not fetch the video URL.
photo_pull_failedTikTok could not fetch the image URL.
invalid_file_uploadFile failed TikTok's upload validation.
rate_limit_exceededToo many API requests in a short window.
too many requestsGeneric 429 from TikTok's gateway.
unaudited_client_can_only_post_to_private_accountsYour TikTok app has not been audited yet.
url_ownership_unverifiedYou tried to attach a domain you have not verified.
privacy_level_option_mismatchRequested privacy level is not allowed for this app/account.
internalTikTok server-side failure.
invalid_paramsA required parameter is missing or malformed.

Other platforms

Instagram errors

33 documented

X (Twitter) errors

12 documented

Facebook errors

15 documented

LinkedIn errors

9 documented

Bluesky errors

10 documented

Pinterest errors

8 documented

Threads errors

7 documented

YouTube errors

15 documented

Ready to Add Social Media to Your Product?

One API. Every platform. Start building with free credits.

Start Posting for FreeNo credit card required.
POST https://api.postpeer.dev/v1/posts
{ "platforms": ["twitter", "linkedin", "instagram], "content": "Hello world!" }
Published
5 platforms
TwitterLinkedInFacebook+2
All posts delivered
Scheduled
queue
12
Queued
847
Sent
Next: in 15 min
Platforms
connected
XIGFBLITT
One API, every platform