access_token_invalidReconnectTikTok rejected the access token.
Reconnect TikTok and create a fresh token for the connected user.
refresh-token
Error reference
TikTok API errors and troubleshooting
Diagnose TikTok API errors that block creator authorization, video pulls, photo mode uploads, privacy settings, spam checks, and rate limits. Use this reference to decide whether a TikTok post needs a new token, a cleaner media export, slower scheduling, or app-review changes.
Last updated: May 2026
25 documented error patterns across 7 categories
Clear guidance on reconnecting, retrying, replacing media, or changing content
Official platform references plus bundle.social production troubleshooting notes
Error categories
Find the failure type first
25 documented errors
All error codes
Codes, causes, and fixes
Authentication
3 mapped cases
scope_not_authorizedReconnectThe token is missing a TikTok scope required for this action.
Reconnect the account and approve all requested posting and profile scopes.
refresh-token
scope_permission_missedReconnectTikTok needs an additional permission for the request.
Re-authenticate the user and confirm the app has approval for the requested capability.
refresh-token
Spam
6 mapped cases
spam_risk_user_banned_from_postingFix inputThe TikTok account is restricted from posting.
Ask the user to open TikTok, check account status, and resolve any posting restriction or appeal.
user-error
spam_risk_textFix inputTikTok flagged the caption or text as spam.
Change repetitive copy, promotional wording, excessive links, or hashtags before retrying.
user-error
spam_risk_too_many_postsFix inputThe account hit TikTok posting volume limits.
Wait for the posting window to reset and spread scheduled posts over time.
user-error
spam_risk_too_many_pending_shareFix inputThe user has too many pending API shares.
Wait until existing pending shares are completed or expire before creating another upload.
user-error
spam_riskFix inputTikTok blocked the post as risky or automated.
Publish more original content and reduce repeated automated posting patterns.
user-error
reached_active_user_capFix inputThe TikTok app reached its active user quota.
Wait for quota reset or request higher production limits from TikTok.
user-error
Video Format
6 mapped cases
file_format_check_failedFix inputThe video container or format is not accepted by TikTok.
Re-export as MP4 or WebM and verify the file is playable before upload.
user-error
duration_check_failedFix inputThe video duration is outside TikTok limits.
Trim the video into an accepted duration before retrying.
user-error
frame_rate_check_failedFix inputThe video frame rate is invalid.
Re-encode the video at a supported frame rate such as 30 or 60 fps.
user-error
picture_size_check_failedFix inputThe video resolution is too low or otherwise invalid.
Use a higher-resolution export, typically at least 720p.
user-error
video durationFix inputThe video is too long for the selected TikTok publishing path.
Shorten the asset or split it into separate posts.
user-error
file sizeFix inputThe media file exceeds TikTok size limits.
Compress the file or lower bitrate while preserving an accepted format.
user-error
Media
3 mapped cases
video_pull_failedRetry laterTikTok could not download the video URL.
Use a public HTTPS URL with direct media bytes, correct headers, and enough lifetime for processing.
retry
photo_pull_failedRetry laterTikTok could not download the photo URL.
Check URL access, content type, redirects, and signed URL expiry.
retry
invalid_file_uploadFix inputThe uploaded file is invalid or does not match TikTok specs.
Replace the asset with a clean export that matches TikTok image or video requirements.
user-error
Rate Limit
2 mapped cases
rate_limit_exceededRetry laterTikTok rate limited the request.
Retry with backoff instead of sending the same request immediately.
retry
too many requestsRetry laterTikTok received too many requests in a short window.
Queue requests and slow down API calls for the affected account or app.
retry
App Status
3 mapped cases
unaudited_client_can_only_post_to_private_accountsFix inputThe TikTok app is not approved for public posting.
Complete TikTok app review before allowing public posts from production users.
user-error
url_ownership_unverifiedFix inputTikTok requires domain ownership verification for a URL in the post.
Verify the domain in TikTok developer settings or remove the URL.
user-error
privacy_level_option_mismatchFix inputThe requested privacy level is not allowed for this app or user.
Use a privacy level returned by TikTok for the connected creator.
user-error
Server
2 mapped cases
internalRetry laterTikTok returned an internal service error.
Retry later with backoff and keep the raw response for support.
retry
invalid_paramsFix inputTikTok rejected one or more request parameters.
Validate required fields, media type, privacy level, caption, and upload IDs before retrying.
user-error
Missing scope or permission
Publishing and analytics calls require the correct OAuth scopes. If a user skipped a scope or your app lacks approval for it, the request can fail before content is evaluated.
Invalid file upload
Video and photo posts must match TikTok media requirements. Re-export the file, check image format, shorten oversized videos, and retry with a clean upload.
Most TikTok publishing failures are not OAuth problems
If the account is already connected and the token is valid, TikTok failures usually come from media validation, spam risk, privacy-level mismatch, app-review state, or posting volume. Reconnecting the account will not fix unsupported files, spam-risk responses, or unaudited app limitations.
Check the creator state before retrying
TikTok publishing depends on the connected creator account, allowed privacy levels, app approval, media type, and recent posting behavior. Before retrying, confirm that the selected privacy option is available for that creator and that the media file matches the selected TikTok publishing flow.
How bundle.social helps
bundle.social separates TikTok failures into OAuth, creator eligibility, app-review state, media validation, spam risk, privacy-level mismatch, and temporary platform limits. This helps teams quickly decide whether the user needs to reconnect, replace the file, slow down posting, or change app settings.
Retry safety
Retry only temporary platform failures, processing delays, timeouts, 5xx responses, and rate-limit errors after the platform allows it. Do not retry the same request when the failure is caused by expired tokens, missing permissions, unsupported media, invalid captions, duplicate content, account restrictions, or policy blocks. The same payload will usually fail again until the account, media, content, or platform-specific setting is fixed.
Official references
Platform APIs change. Use these links to confirm current error behavior and field support.
FAQ
Can TikTok API error messages change over time?
TikTok error names are readable, but the same publishing problem can surface through spam risk, media pull, privacy, or app status codes. Treat the code as the starting point, then verify the affected creator account, upload asset, and app approval state.
Should users reconnect the account for every failed post?
No. Reconnect TikTok for access token, scope, or creator authorization failures. For video format, spam risk, privacy level, or rate-limit errors, fix the asset, caption, schedule, or app setting before sending the post again.
Does bundle.social hide the native platform error?
bundle.social keeps TikTok's native response available while translating it into the next operational step, such as reconnecting, replacing media, slowing down posts.
Related
Keep researching
Build with less platform drag