登入開始免費試用
easyCoexistence 官方 API

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 的原因,並可隨時重試。

reason

/business/publish/status/ 僅在狀態為 FAILED 時返回,其值包括 frame_rate_check_failed 等。

fail_reason

Content Posting API 在 /v2/post/publish/status/fetch/ 回應中,對同一欄位的命名。

1 hour

下載逾時:逾時後 TikTok 會以 video_pull_failed 或 photo_pull_failed 使貼文失敗。

24 hours

spam_risk_too_many_posts 背後的時間窗口;TikTok 建議改由 TikTok 手機應用程式發布該貼文。

3 hours

大多數情況下,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 欄位返回相同原因。

A failed post in /business/publish/status/, from TikTok's example
{
  "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 foundThe fix
file_format_check_failedThe file's format breaks TikTok's specificationsMP4, MOV or WebM video; JPG, JPEG or WebP photos
duration_check_failedThe video's length is outside the limitsAt least 3 seconds, within the account's maximum
frame_rate_check_failedBelow 23 or above 60 frames per secondExport at 23 to 60 FPS
picture_size_check_failedHeight or width under 360 pixelsAt least 360 pixels on each side
video_pull_failed, photo_pull_failedThe download failed or ran past one hourA public URL that is not bandwidth-limited, then a retry
internalPart of TikTok's service was unavailableA retry
auth_removedThe owner removed the app's access mid-processingNo retry; the owner authorizes the app again
spam_risk_too_many_postsToo many API posts in the last 24 hoursPosting from the TikTok mobile app, or waiting
spam_risk_user_banned_from_postingThe account is banned from making new postsNo retry while the account cannot post
spam_risk_textThe caption reads as risky or spammyNew text before posting again
spam_riskHigh spam risk, such as attempts made too oftenNo retry, as TikTok advises
publish_cancelledThe upload or download was cancelledPublishing 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。需要更換檔案或文字說明的貼文,則會改為重新排程。

Failed posts through MCP
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。
使用 EasyCoexistence 完成這項設定

每個連接每月由 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 監察

驗證日期