TikTok 發布失敗原因:spam_risk_too_many_posts、picture_size_check_failed 等及其修正方法
TikTok 會在 API for Business 的狀態端點以 reason 標示貼文失敗原因,在 Content Posting API 則以 fail_reason 標示。picture_size_check_failed 等檢查類失敗表示檔案違反格式規則,需要更換檔案;video_pull_failed 表示 TikTok 無法在一小時內下載檔案;spam_risk_too_many_posts 表示 24 小時內經 API 發布的貼文過多。標示為 internal 的失敗只需重試即可。
easyCoexistence 會持續跟進其發布的每則 TikTok 貼文,直至 TikTok 完成或使其失敗,無論是供 Claude、ChatGPT 或您自己的平台使用:失敗時會以電郵、於「貼文」頁面及 post.failed 事件附上 TikTok 的原因,並可隨時重試。
/business/publish/status/ 僅在狀態為 FAILED 時返回,其值包括 frame_rate_check_failed 等。
Content Posting API 在 /v2/post/publish/status/fetch/ 回應中,對同一欄位的命名。
下載逾時:逾時後 TikTok 會以 video_pull_failed 或 photo_pull_failed 使貼文失敗。
spam_risk_too_many_posts 背後的時間窗口;TikTok 建議改由 TikTok 手機應用程式發布該貼文。
大多數情況下,easyCoexistence 會以電郵通知擁有者某個頻道的貼文失敗;該貼文會留在「需要處理」下等候。
TikTok 在哪裡說明貼文失敗的原因?
發布呼叫僅啟動任務:其返回代碼 0 表示 TikTok 已接收,但不代表貼文一定會上線。隨後呼叫 GET /business/publish/status/,若狀態為 FAILED,會讀取 reason;已訂閱發布 Webhook 的應用程式,會收到 post.publish.failed 事件,當中含相同的 reason 與 publish_id。Content Posting API 的 /v2/post/publish/status/fetch/ 則以 fail_reason 欄位返回相同原因。
{
"code": 0,
"message": "OK",
"request_id": "<REQUEST_ID>",
"data": {
"reason": "frame_rate_check_failed",
"status": "FAILED"
}
}各項失敗原因代表什麼,應如何修正?
以下為依 TikTok 貼文發布事件參考文件所述的失敗原因,並列出各原因對應的修正方法。前四項是 TikTok 下載檔案後進行的檢查,均標示為不可重試。TikTok 的失敗表仍將 duration_check_failed 的最長影片時長定為 60 秒,但影片端點的文件記載為 600 秒,或為該帳戶自身的 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 |
哪些失敗可以重試?
由下載過程或 TikTok 本身所引致的失敗可以重試。其餘失敗則需要不同的檔案或文字說明、暫停一段時間,或無需任何處理:
- 原樣重試:internal,以及
video_pull_failed或photo_pull_failed(待網址公開且速度足夠快之後)。 - 更換檔案後重試:
file_format_check_failed、duration_check_failed、frame_rate_check_failed及picture_size_check_failed。 - 更換文字說明後重試:
spam_risk_text。 - 等待,或改由 TikTok 應用程式發布:
spam_risk_too_many_posts。 - 請勿重試:依 TikTok 的建議,
auth_removed與spam_risk;或spam_risk_user_banned_from_posting。
Content Posting API 的失敗有何不同?
原因相同,但欄位和端點不同,且有些拒絕會在處理開始前發生。/v2/post/publish/status/fetch/ 返回 fail_reason,每個用戶權杖每分鐘可發出 30 次請求,並對 spam_risk_user_banned_from_posting 與 spam_risk_text 加入請勿重試的建議。若干拒絕會改在初始化呼叫時以 HTTP 403 返回:
spam_risk_too_many_posts:創作者已達到 API 每日貼文上限。unaudited_client_can_only_post_to_private_accounts:未經審核的應用程式嘗試為公開帳戶發布貼文。url_ownership_unverified:應用程式以PULL_FROM_URL從未經驗證的網域或前綴發布。privacy_level_option_mismatch:privacy_level欄位缺失,或超出創作者可選的範圍。reached_active_user_cap:應用程式已達到其每日活躍發布用戶配額。
哪些失敗會在 TikTok 處理貼文之前發生?
由 easyCoexistence 率先攔截的失敗,會以其本身的訊息顯示,而非 TikTok 的原因。已排程貼文的媒體會在排程時複製,若連結返回網頁、404 或類型錯誤,又或圖片檔案超過 30 MB、影片檔案超過 1 GB,便會在那時被拒絕。以 .png、.gif、.bmp、.heic、.avif 或 .svg 結尾的圖片連結會在任何內容發送前被拒絕;需要在發布時重新連接的頻道會以 reconnect 失敗;移除頻道則會取消其已排程的貼文。
easyCoexistence 如何報告失敗的 TikTok 貼文?
透過其發布隊列,在發布呼叫之後持續跟進每則 TikTok 貼文,約每 20 秒檢查一次 /business/publish/status/,直至 PUBLISH_COMPLETE。狀態為 FAILED 時,該貼文即告失敗,錯誤訊息會以括號列出 TikTok 的原因,例如 frame_rate_check_failed,每項失敗並附有 failure_kind:
- refused:TikTok 明確拒絕,例如狀態為 FAILED 並附原因。
- uncertain:發布呼叫未得到明確回應,或 TikTok 於 2 小時內未作確認,因此貼文可能已上線(
may_be_published)。 - reconnect:TikTok 拒絕了該帳戶的權杖,需要重新登入。
- internal:easyCoexistence 在移交貼文前失敗,因此沒有任何內容發出。
如何找到並重試失敗的貼文?
擁有者會在後台發現失敗時收到電郵,每個頻道每 3 小時最多一封;平台的事件網址亦會收到 post.failed。該貼文會顯示於「貼文」頁面的「需要處理」下,並附有「重試」、「重新連接」及「忽略」按鈕;list_scheduled_posts 會將其回傳給 Claude 或 ChatGPT。retry_scheduled_post 會立即重新發布該貼文,所用檔案會在失敗後保留 7 天。當 may_be_published 為 true 時,請先檢查 list_social_posts,只有確認貼文不存在時,才傳入 confirm。需要更換檔案或文字說明的貼文,則會改為重新排程。
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 }常見錯誤
- 以相同檔案重試檢查類失敗。TikTok 將格式、時長、幀率及圖片尺寸的失敗均標示為不可重試。
- 立即重試 spam_risk_too_many_posts。TikTok 會計算 24 小時內的 API 貼文數量,並建議改由手機應用程式發布。
- 未經查看便重試標示為 may_be_published 的貼文。TikTok 可能已經發布該貼文;請先檢查帳戶最近的貼文,否則貼文會發布兩次。
- 在 API for Business 中尋找 fail_reason。其狀態端點的欄位名稱為 reason;fail_reason 屬於 Content Posting API。
每個連接每月由 US$ 9 降至 US$ 0.75,連接越多越便宜,首 3 天免費。
常見問題
picture_size_check_failed 在 TikTok 上是什麼意思?
TikTok 下載貼文後,發現圖片的高度或寬度低於 360 像素的最低要求;需要使用更大的檔案。由於 TikTok 將此失敗標示為不可重試,因此不能原樣重試。
什麼是 video_pull_failed?
TikTok 無法從網址下載影片,或未能在一小時的逾時時限內完成下載。請檢查網址是否公開且沒有頻寬限制,然後再重試。
spam_risk_too_many_posts 會持續多久?
TikTok 會計算過去 24 小時內透過 API 發布的貼文,每個帳戶約為每日 15 則;期間建議改用 TikTok 手機應用程式發布。
easyCoexistence 會自動重試失敗的 TikTok 貼文嗎?
TikTok 報告 FAILED 後不會自動重試:貼文會留在「需要處理」下,擁有者會收到電郵,而重試或 retry_scheduled_post 會再次發送。
繼續閱讀
兩分鐘內連接您的第一個頻道。
無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。
- 免費試用 3 天
- 隨時取消
- 只用官方 API
- 24/7 監察
驗證日期