TikTok publish failures: spam_risk_too_many_posts, picture_size_check_failed and other fail reasons
TikTok names a failed post's cause in reason, on the API for Business status endpoint, or fail_reason on the Content Posting API. Check failures such as picture_size_check_failed mean the file breaks a format rule and needs changing; video_pull_failed means TikTok could not download it within an hour; spam_risk_too_many_posts means too many API posts in 24 hours. A failure marked internal can simply be retried.
easyCoexistence follows each TikTok post it publishes until TikTok completes or fails it, for Claude, ChatGPT or your own platform: a failure arrives with TikTok's reason by email, on the Posts screen and as a post.failed event, ready to retry.
Field /business/publish/status/ returns only when status is FAILED, with values such as frame_rate_check_failed.
The Content Posting API's name for the same field, in /v2/post/publish/status/fetch/ responses.
Download timeout after which TikTok fails a post with video_pull_failed or photo_pull_failed.
Window behind spam_risk_too_many_posts; TikTok suggests publishing that post from its mobile app instead.
Most often easyCoexistence emails an owner about failed posts on one channel; the post waits under Needs attention.
Where does TikTok report why a post failed?
After the publish call, which only starts the task: its code 0 means TikTok accepted it, not that the post will go live. GET /business/publish/status/ then reads FAILED with reason, and an app subscribed to publishing webhooks receives post.publish.failed with the same reason and the publish_id. The Content Posting API's /v2/post/publish/status/fetch/ returns the field as fail_reason:
{
"code": 0,
"message": "OK",
"request_id": "<REQUEST_ID>",
"data": {
"reason": "frame_rate_check_failed",
"status": "FAILED"
}
}What does each fail reason mean, and what fixes it?
TikTok's reasons, as its post publishing events reference describes them, beside the fix each points to. The first four are checks TikTok runs on the file after downloading it, all marked as not retryable. TikTok's failure table still gives 60 seconds as the longest video for duration_check_failed, while the video endpoint documents 600, or the account's own max_video_post_duration_sec:
| What TikTok found | The fix | |
|---|---|---|
| file_format_check_failed | The file's format breaks TikTok's specifications | MP4, MOV or WebM video; JPG, JPEG or WebP photos |
| duration_check_failed | The video's length is outside the limits | At least 3 seconds, within the account's maximum |
| frame_rate_check_failed | Below 23 or above 60 frames per second | Export at 23 to 60 FPS |
| picture_size_check_failed | Height or width under 360 pixels | At least 360 pixels on each side |
| video_pull_failed, photo_pull_failed | The download failed or ran past one hour | A public URL that is not bandwidth-limited, then a retry |
| internal | Part of TikTok's service was unavailable | A retry |
| auth_removed | The owner removed the app's access mid-processing | No retry; the owner authorizes the app again |
| spam_risk_too_many_posts | Too many API posts in the last 24 hours | Posting from the TikTok mobile app, or waiting |
| spam_risk_user_banned_from_posting | The account is banned from making new posts | No retry while the account cannot post |
| spam_risk_text | The caption reads as risky or spammy | New text before posting again |
| spam_risk | High spam risk, such as attempts made too often | No retry, as TikTok advises |
| publish_cancelled | The upload or download was cancelled | Publishing again if the post is still wanted |
Which failures can be retried?
Those caused by the download or by TikTok itself. The rest need a different file or caption, a pause, or nothing at all:
- Retry as is: internal, and
video_pull_failedorphoto_pull_failedonce the URL is public and fast enough. - Retry with a new file:
file_format_check_failed,duration_check_failed,frame_rate_check_failedandpicture_size_check_failed. - Retry with a new caption:
spam_risk_text. - Wait, or post from the TikTok app:
spam_risk_too_many_posts. - Do not retry:
auth_removedandspam_risk, as TikTok advises, orspam_risk_user_banned_from_posting.
How do the Content Posting API's failures differ?
Same reasons, a different field and endpoint, and refusals that come before processing starts. /v2/post/publish/status/fetch/ returns fail_reason, allows 30 requests a minute per user token, and adds do-not-retry advice for spam_risk_user_banned_from_posting and spam_risk_text. Several refusals arrive at the init call instead, with HTTP 403:
spam_risk_too_many_posts: the creator reached the API's daily post cap.unaudited_client_can_only_post_to_private_accounts: an unaudited app tried to post for a public account.url_ownership_unverified:PULL_FROM_URLfrom a domain or prefix the app has not verified.privacy_level_option_mismatch: aprivacy_levelmissing or outside the creator's options.reached_active_user_cap: the app reached its daily quota of active publishing users.
What fails before TikTok sees the post?
What easyCoexistence can catch first, with a message of its own instead of a TikTok reason. A scheduled post's media is copied when it is scheduled, and a link that returns a web page, a 404, the wrong type, or a file over 30 MB for an image or 1 GB for a video is refused then. Photo links ending in .png, .gif, .bmp, .heic, .avif or .svg are refused before anything is sent, a channel that needs reconnecting at post time fails as reconnect, and removing a channel cancels its scheduled posts.
How does easyCoexistence report a failed TikTok post?
Through its posting queue, which follows each TikTok post after the publish call, checking /business/publish/status/ about every 20 seconds until PUBLISH_COMPLETE. A FAILED status fails the post, whose error names TikTok's reason in parentheses, such as frame_rate_check_failed, and each failure carries a failure_kind:
- refused: TikTok answered no, as with a FAILED status and its reason.
- uncertain: the publish call got no clear answer, or TikTok gave no confirmation within 2 hours, so the post may be live (
may_be_published). - reconnect: TikTok refused the account's token, and the account needs a new sign-in.
- internal: easyCoexistence failed before handing the post over, so nothing went out.
How do you find and retry a failed post?
The owner gets an email for a failure found in the background, at most one per channel every 3 hours, and a platform's events URL receives post.failed. The post shows under Needs attention on the Posts screen, with Retry, Reconnect and Dismiss, and list_scheduled_posts returns it to Claude or ChatGPT. retry_scheduled_post publishes it again, now, from files kept 7 days after a failure; when may_be_published is true, check list_social_posts first and pass confirm only if the post is missing. A post that needs a new file or caption is scheduled again instead.
list_scheduled_posts { "account_id": "<ACCOUNT_ID>", "status": ["failed"] }
retry_scheduled_post { "post_id": "<POST_ID>" }
// may_be_published is true and the post is not on the account
retry_scheduled_post { "post_id": "<POST_ID>", "confirm": true }Common mistakes
- Retrying a check failure with the same file. TikTok marks the format, duration, frame rate and picture size failures as not retryable.
- Retrying spam_risk_too_many_posts at once. TikTok counts API posts over 24 hours and suggests posting from the mobile app.
- Retrying a post marked may_be_published without looking. TikTok may have published it; check the account's latest posts, or it goes out twice.
- Looking for fail_reason on the API for Business. Its status endpoint names the field reason; fail_reason belongs to the Content Posting API.
US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.
easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.
Frequently asked questions
What does picture_size_check_failed mean on TikTok?
TikTok downloaded the post and found its picture below the minimum of 360 pixels in height and width; it needs a larger file, since TikTok marks the failure as not retryable.
What is video_pull_failed?
TikTok could not download the video from its URL, or not within the one-hour timeout. Check that the URL is public and not bandwidth-limited, then retry.
How long does spam_risk_too_many_posts last?
TikTok counts posts made through the API over the last 24 hours, about 15 a day per account, and suggests publishing from the TikTok mobile app meanwhile.
Does easyCoexistence retry a failed TikTok post on its own?
Not after TikTok reports FAILED: the post waits under Needs attention and the owner is emailed, and Retry or retry_scheduled_post sends it again.
Keep reading
Connect your first channel in two minutes.
No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.
- 3 days free
- Cancel any time
- Official APIs only
- Monitored 24/7
Verified on