Skip to content

TikTok API errors

TikTok API errors cover more than a bad request. The TikTok Content Posting API validates authentication, scopes, spam signals, video format, media access, rate limits, app audit status, and privacy options before a post can publish. This reference groups all 25 documented codes by category so you can find the cause, apply the concrete fix, and decide whether to reconnect, re-encode, wait, verify, or correct the request.

TikTok API errors overview and how to use the 25-code reference

Use this page by matching the exact code returned for your failed publish, then follow the fix in its category. Authentication errors mean the account connection or granted scopes must change. Spam and posting-cap errors usually require waiting, rewriting, or appealing rather than retrying immediately. Video format and media errors require re-encoding or fixing the media URL before any retry. Rate limit and server errors are the main cases where backoff helps. App status errors require audit or domain verification, and invalid_params requires correcting the request contract. The Quick Reference table below lists all 25 codes, and the Failure Matrix table maps each code to its fix type and retryability. The Pre-Publish Checklist table turns the source constraints into checks you can run before submitting.

Authentication errors: token and scope fixes

access_token_invalid means TikTok rejected the access token. Tokens expire 24 hours after issue, and if the refresh token is also gone or stale the integration cannot recover on its own. Reconnect the TikTok account to mint a new token pair. Because TikTok refresh tokens are single-use, any refresh flow must persist the rotated refresh token immediately or the next refresh will fail. scope_not_authorized means a required scope was not granted during OAuth. TikTok's consent screen lets users opt out of individual scopes, and posting requires video.upload or video.publish plus user.info.basic. Repeat the connection flow and make sure each requested scope is approved. scope_permission_missed is the same underlying problem raised at call time instead of at token introspection. Reconnect with the additional scope requested in the OAuth URL. In all three cases, retrying the same publish with the same token will not help; reconnect first, then retry once.

Spam and posting cap errors: what to wait for versus rewrite or appeal

spam_risk_user_banned_from_posting means TikTok banned the account from publishing, usually after repeated community-guideline violations or rapid automated posting. Open the TikTok app, check any warnings there, and submit an appeal when the restriction seems mistaken. spam_risk_text means TikTok detected spam in the caption text, often from repetitive phrasing, excessive links, or promotional copy patterns. Rewrite the caption with original phrasing. spam_risk_too_many_posts means the account hit its 24-hour posting cap. Pause for a full day or distribute posts across several accounts. spam_risk_too_many_pending_share means too many shares are queued in TikTok's pending state, with a maximum of 5 pending API shares per user per 24-hour window. Let queued shares finish publishing or review before adding more. spam_risk is a generic spam-detection match where the content fingerprint matched something already flagged. Re-shoot or significantly edit the video, because trivial changes will still match. reached_active_user_cap means your TikTok app hit its daily active-user quota, which applies to unaudited apps with a hard cap on daily distinct users. Send the app for TikTok review to raise the cap, or pause for 24 hours. None of these are fixed by immediate retries; waiting, rewriting, appealing, or audit are the correct actions.

Video format errors: pre-publish encoding checklist

file_format_check_failed means TikTok did not accept the video container or codec. Anything outside MP4 with H.264 video, or WebM, is rejected. Convert the file to MP4 using H.264 video and AAC audio. duration_check_failed means video duration is outside TikTok's accepted range of 3 seconds to 10 minutes for API uploads. Extend very short clips to reach 3 seconds, or shorten long ones to stay under 10 minutes. frame_rate_check_failed means the frame rate is outside the 23 to 60 fps band. Convert at 30 fps for safe compatibility. picture_size_check_failed means resolution is below 720p, and TikTok rejects sub-HD video on the Content Posting API. Export again from a source at 720p or higher. The video duration error is the same 10-minute maximum raised in a different layer; trim or split into a multi-part series. The file size error means the video exceeds the roughly 287MB upload cap enforced by the pull-from-URL endpoint. Convert with a lower bitrate or shorter duration. Check all of these constraints before publishing, because a file that fails one check will fail again unchanged.

Media fetch errors: fixing the URL before retrying

video_pull_failed means TikTok could not fetch the video URL. The URL was unreachable, returned a non-200 status, had the wrong Content-Type, or was redirected. Serve the file from a public URL returning video/mp4 with no redirects. photo_pull_failed has the same shape for photo posts; use a public URL returning image/jpeg or image/png. invalid_file_upload means the file failed TikTok's upload validation, usually a combination of size, codec, or format mismatch. Compare the file against the Content Posting specifications and export again. Before retrying, fetch the URL yourself with the same method TikTok would use and confirm the status code, Content-Type, and absence of redirects.

Rate limit errors: backoff and jitter

rate_limit_exceeded, returned as HTTP 429, means too many API requests in a short window. TikTok limits both per-app and per-user request rates. Back off exponentially and respect the Retry-After header when present. The too many requests error is a generic 429 from TikTok's gateway caused by a burst of requests from the same app or user. Add jitter to your retry logic so concurrent workers do not retry in lockstep. The Retry handling and privacy level selection example shows exponential backoff with jitter and Retry-After handling for these cases.

App status errors: audit, verification, and privacy level

unaudited_client_can_only_post_to_private_accounts means your TikTok app has not been audited yet. Apps without audit are limited to private, self-only posting no matter which privacy level the user asked for. Request TikTok's Content Posting audit to enable public posting. url_ownership_unverified means you tried to attach a domain you have not verified. TikTok requires domain verification for any external URL embedded in a post. Prove ownership in TikTok's developer console using DNS or .well-known proof. privacy_level_option_mismatch means the requested privacy level is not allowed for this app or account. The creator's allowed privacy_level_options did not include the value you sent. Fetch creator info first and choose a value from the returned privacyLevelOptions array. The Retry handling and privacy level selection example shows how to choose a privacy level from the returned options instead of guessing.

Server and contract errors: 500 versus 400

internal, returned as HTTP 500, means a TikTok server-side failure, usually a transient outage or partial dependency failure. Retry with exponential backoff. invalid_params, returned as HTTP 400, means a required parameter is missing or malformed. The API contract was not followed, usually a missing post_info field or a wrong enum value. Compare your request body against the specification for the endpoint and correct the field before retrying. A 400 should not be retried unchanged, while a 500 is the server-error case where backoff is appropriate.

Quick reference table

Search the Quick Reference table for your exact code to confirm its category and meaning. Then use the Failure Matrix table to decide the fix type and whether a retry is appropriate, and run the Pre-Publish Checklist table before your next attempt. If the code is access_token_invalid, scope_not_authorized, or scope_permission_missed, reconnect. If it is file_format_check_failed, duration_check_failed, frame_rate_check_failed, picture_size_check_failed, video duration, file size, video_pull_failed, photo_pull_failed, or invalid_file_upload, fix the file or URL. If it is rate_limit_exceeded, too many requests, or internal, back off. If it is unaudited_client_can_only_post_to_private_accounts, url_ownership_unverified, or privacy_level_option_mismatch, complete audit, verification, or privacy selection. If it is invalid_params, correct the request.

Field map: all 25 TikTok API errors by category, cause, fix, and retryability
CodeCategoryWhat it meansCauseFixRetryability
access_token_invalidAuthenticationTikTok rejected the access token.Token expired after 24 hours and refresh token gone or stale.Reconnect the TikTok account to mint a new token pair.No — reconnect first
scope_not_authorizedAuthenticationRequired scope was not granted during OAuth.User opted out of a scope on the consent screen; posting requires video.upload or video.publish plus user.info.basic.Run the connect flow again and approve every requested scope.No — reconnect first
scope_permission_missedAuthenticationOperation needs a scope the token does not have.Same scope gap as scope_not_authorized, raised at call time.Reconnect with the additional scope requested in the OAuth URL.No — reconnect first
spam_risk_user_banned_from_postingSpamTikTok banned the account from publishing.Repeated community-guideline violations or rapid automated posting.Review warnings in the TikTok app and appeal if applied in error.No — appeal/wait
spam_risk_textSpamTikTok detected spam in the caption text.Repetitive phrasing, excessive links, or promotional copy patterns.Rewrite the caption with original phrasing.No — rewrite first
spam_risk_too_many_postsSpamAccount hit its 24-hour posting cap.Too many posts from one account in 24 hours via the API.Wait 24 hours or spread posts across multiple accounts.Wait 24 hours
spam_risk_too_many_pending_shareSpamToo many shares are queued in TikTok's pending state.Maximum 5 pending API shares per user per 24-hour window.Wait for pending shares to publish or be reviewed.Wait
spam_riskSpamGeneric spam-detection match.Content fingerprint matched something already flagged.Re-shoot or significantly edit the video.No — new content first
reached_active_user_capSpamYour TikTok app hit its daily active-user quota.Unaudited apps have a hard cap on daily distinct users.Submit the app for TikTok review, or wait 24 hours.Wait or audit
file_format_check_failedVideo formatTikTok did not accept the video container/codec.Container/codec outside MP4 (H.264) or WebM.Re-encode to MP4 with H.264 video and AAC audio.No — re-encode first
duration_check_failedVideo formatVideo duration is outside TikTok's accepted range.Accepted range is 3 seconds to 10 minutes for API uploads.Trim clips to at least 3s and under 10 minutes.No — re-encode first
frame_rate_check_failedVideo formatFrame rate is outside 23–60 fps.Ingestion enforces a 23–60 fps frame rate band.Re-encode at 30 fps.No — re-encode first
picture_size_check_failedVideo formatResolution is below 720p.TikTok rejects sub-HD video on the Content Posting API.Re-export from a 720p or higher source.No — re-export first
video durationVideo formatVideo is longer than TikTok's 10-minute API max.Same 10-minute maximum as duration_check_failed, raised in a different layer.Trim or split into a multi-part series.No — trim first
file sizeVideo formatVideo file exceeds ~287MB upload cap.Pull-from-URL endpoint enforces a hard byte cap.Re-encode with lower bitrate or shorter duration.No — re-encode first
video_pull_failedMediaTikTok could not fetch the video URL.URL unreachable, non-200, wrong Content-Type, or redirected.Serve from a public URL returning video/mp4 with no redirects.No — fix URL first
photo_pull_failedMediaTikTok could not fetch the image URL.Same fetch failure shape as video_pull_failed for photo posts.Use a public URL returning image/jpeg or image/png.No — fix URL first
invalid_file_uploadMediaFile failed TikTok's upload validation.Combination of size, codec, or format mismatch.Cross-check against Content Posting specs and re-export.No — re-export first
rate_limit_exceededRate limitToo many API requests in a short window.Per-app and per-user request rate limits; HTTP 429.Back off exponentially and respect Retry-After.Yes — with backoff
too many requestsRate limitGeneric 429 from TikTok's gateway.Burst of requests from the same app or user.Add jitter to retry logic.Yes — with backoff and jitter
unaudited_client_can_only_post_to_private_accountsApp statusYour TikTok app has not been audited yet.Unaudited apps can only post in private (self-only) mode.Submit the app for TikTok's Content Posting audit.No — audit first
url_ownership_unverifiedApp statusYou tried to attach a domain you have not verified.TikTok requires domain verification for external URLs in a post.Verify ownership via DNS or .well-known proof in the developer console.No — verify first
privacy_level_option_mismatchApp statusRequested privacy level is not allowed for this app/account.Value not in the creator's privacy_level_options / privacyLevelOptions.Pull creator info first and pick a value from the returned array.No — correct value first
internalServerTikTok server-side failure.Transient outage or partial dependency failure; HTTP 500.Retry with exponential backoff.Yes — with backoff
invalid_paramsServerA required parameter is missing or malformed.Contract not followed, usually a missing post_info field or wrong enum; HTTP 400.Diff the request body against the endpoint specification and correct it.No — correct request first

Source-described error reference; retryability is editorial guidance derived from the source fix for each code.

Failure matrix: reconnect, re-encode, wait/backoff, audit/verification, and contract fixes
Fix typeCodesDecision rule
Reconnectaccess_token_invalid, scope_not_authorized, scope_permission_missedToken or scope problem: reconnect and re-approve scopes before any retry.
Re-encode / fix mediafile_format_check_failed, duration_check_failed, frame_rate_check_failed, picture_size_check_failed, video duration, file size, video_pull_failed, photo_pull_failed, invalid_file_uploadFile or URL problem: change the file or URL, then retry once.
Wait / backoffspam_risk_too_many_posts, spam_risk_too_many_pending_share, reached_active_user_cap, rate_limit_exceeded, too many requests, internalTime or transient problem: wait the stated window or back off with jitter and Retry-After.
Rewrite / appealspam_risk_user_banned_from_posting, spam_risk_text, spam_riskContent or account problem: rewrite, re-shoot, or appeal; do not retry unchanged.
Audit / verificationunaudited_client_can_only_post_to_private_accounts, url_ownership_unverified, privacy_level_option_mismatchApp-status problem: complete audit, domain verification, or select an allowed privacy level.
Correct request contractinvalid_paramsHTTP 400: fix the missing or malformed parameter; do not retry unchanged.

Editorial grouping of source fixes; use the exact code to confirm before acting.

Worked pre-publish checklist using video, privacy, scope, and media URL constraints
CheckPass conditionError it prevents
Token and scopesToken is within its 24-hour life and video.upload or video.publish plus user.info.basic were granted.access_token_invalid, scope_not_authorized, scope_permission_missed
Container and codecMP4 with H.264 video and AAC audio, or WebM.file_format_check_failed, invalid_file_upload
DurationBetween 3 seconds and 10 minutes.duration_check_failed, video duration
Frame rateBetween 23 and 60 fps; 30 fps is a safe target.frame_rate_check_failed
Resolution720p or higher.picture_size_check_failed
File sizeAt or below roughly 287MB.file size
Media URLPublic URL returns 200 with video/mp4 for video or image/jpeg or image/png for photos, with no redirects.video_pull_failed, photo_pull_failed
Privacy levelValue selected from the creator's returned privacyLevelOptions array.privacy_level_option_mismatch
App audit statusApp audited if public posting is required; unaudited apps are limited to private (self-only) mode.unaudited_client_can_only_post_to_private_accounts
Domain verificationAny external URL domain verified via DNS or .well-known proof.url_ownership_unverified
Posting volumeWithin the account's 24-hour posting cap and at most 5 pending API shares per user per 24 hours.spam_risk_too_many_posts, spam_risk_too_many_pending_share

Checklist derived from source constraints for the TikTok Content Posting API.

Frequently asked questions

What should I do when access_token_invalid appears?

Reconnect the account to obtain a fresh token pair, because an expired token with a stale refresh token cannot recover by retrying the same publish.

Should I retry file_format_check_failed or video_pull_failed unchanged?

Re-encode the file and fix the media URL first. Retrying an unchanged file or URL will fail the same checks again.

Are rate_limit_exceeded and internal errors retryable?

Yes, with exponential backoff, jitter, and respect for Retry-After when present. A 400 invalid_params error should not be retried unchanged.