錯誤的 HTTP 狀態碼為 400、401、402、403、404、429、500、502、503 或 504;成功時狀態碼為 200。詳情請見此處。
errors欄位包含錯誤陣列,每個發生錯誤的社群網路各對應一筆。action代表所回傳錯誤的類型。- 最上層的
status欄位在 API 呼叫失敗時為「error」。例如,對於 /post 呼叫,若所有社群網路的貼文皆成功,status欄位會是「success」;否則為「error」。 code欄位為 Ayrshare 的參考錯誤碼。message欄位為錯誤的具體細節。
處理錯誤
你應該處理任何錯誤回應並採取相對應的動作。發生錯誤的情況為:- 回應的狀態碼不是
200 - JSON 回應的 status 為
error
400 Bad Request 回應:
400 Bad Request:
每月發文配額
Code 106 — 超出每月發文配額 (HTTP 429) 此個人資料已用完其每月發文配額。/post 會對新的發文請求回傳此錯誤,包括將貼文排程的請求。其他貼文相關請求(例如取得、刪除或重試貼文,或貼文分析)在配額重設前也會回傳此錯誤。在配額用完期間到期的已排程貼文也會以此代碼失敗。這不是速率限制,等待幾分鐘也無濟於事。
通常,整個回應就是此錯誤:
errors 陣列中。如果在發送新貼文的過程中配額用完,新貼文也可能發生這種情況。請在這兩處都檢查 code: 106。
動作: 透過 User Profile 詳細資料 查看 monthlyPostCount 與 monthlyPostQuota。配額會在每月 1 日(UTC)重設。變更方案會立即重設你的 Primary Profile 的計數。失敗的發文嘗試也會計入,因此請停止自動重試持續失敗的貼文。詳情請參閱我可以發多少貼文與呼叫多少 API?。
重複與相似內容錯誤
在貼文送出至社群平台之前,Ayrshare 會將它與你的其他貼文比對,並以代碼137 拒絕完全相同或高度相似的內容。這是 Ayrshare 自己的檢查,因此即使平台本身會放行,貼文仍可能被拒絕。此檢查並非涵蓋所有平台——請參閱下方的例外情況。
scheduleDate 為中心,在 48 小時的時間窗內進行檢查——前 24 小時到後 24 小時。由於此時間窗同時往前與往後查看,貼文可能會因為排在它之後的貼文而被拒絕,而不只是排在它之前的貼文。
比對的範圍。
- 比對是依使用者檔案(User Profile)與依平台分別進行。同一段文字分別發送到 X/Twitter 與 LinkedIn 不算重複,兩個不同的使用者檔案之間也不會互相衝突。
- X/Twitter 是例外,但僅適用於完全相同的重複內容:完全相同的貼文還會核對同一帳戶下的所有使用者檔案,因為 X 不允許在多個帳號上發布相同內容。高度相似(而非完全相同)的內容檢查仍僅限於發文所用的單一使用者檔案。
- Pinterest、Reddit 與 Telegram 不進行重複檢查。
Instagram 專屬錯誤碼
以下錯誤碼提供 Instagram 發布失敗的具體細節,並在可行時取代較為籠統的 error 138。 Code 435 — Instagram 速率限制 (HTTP 429) Instagram 專業帳號(Business / Creator)在 Meta 的 Content Publishing API 上有 24 小時內滾動 50 篇貼文的限制(個人帳號完全無法透過 API 發布,因此永遠不會觸發此限制)。當達到上限時,Meta 會回傳速率限制錯誤。當 Meta 的發布端點直接回傳 HTTP 429,或底層的 error subcode(1390008)指出貼文/留言遭到節流時,Ayrshare 也會以 code: 435 呈現。
Retry-After 標頭時,其值(單位為秒)會透傳到 details 欄位——至少等待該秒數後再重新提交。
Code 436 — Instagram 媒體處理逾時 (HTTP 400)
Instagram 處理上傳媒體的時間過長。可能發生於大型影片檔或 Meta 伺服器高負載時期。
/post 請求提供了 instagramOptions.trialParams,但 graduationStrategy 為缺失、null 或空字串時回傳。Trial reels 需要明確的 graduation strategy——請參閱 Trial Reels。
instagramOptions.trialParams.graduationStrategy 設為 "MANUAL" 或 "SS_PERFORMANCE" 後重試,或者如果你並非要發布 trial reel,請移除 trialParams。
Code 448 — Instagram Trial Reels:無效的 graduationStrategy (HTTP 400)
當 graduationStrategy 存在但不完全等於 "MANUAL" 或 "SS_PERFORMANCE" 時回傳。此檢查區分大小寫——"manual" 或 "ss_performance" 等值都會被拒絕。details 欄位會回顯被拒絕的輸入(截斷至 64 個字元)以便偵錯。
graduationStrategy 精確地送出為 "MANUAL" 或 "SS_PERFORMANCE"(大寫、字串型別)。
Code 449 — Instagram Trial Reels:不相容的媒體 (HTTP 400)
當媒體或貼文型式不符合 trial reel 的要求時回傳。Trial reels 必須是單一 .mp4 或 .mov 影片——輪播(多個 URL)、限時動態(instagramOptions.stories: true)以及非影片副檔名都會被拒絕。details 欄位會指出實際觸發的子情況。
.mp4 或 .mov 影片網址,且不要帶 stories: true 旗標。移除多餘的 mediaUrls 條目;或者如果你原本要發一般輪播/限時動態,請移除 trialParams。
Code 258 — Instagram 帳號狀態錯誤 (HTTP 400)
一般性的 Instagram 帳號狀態失敗,基礎訊息為「Error with Instagram.」。此錯誤在 Meta 因所連結的 Instagram 帳號狀態(而非貼文內容)拒絕請求時出現。
error_subcode 為 2207085(「Generic Internal Error」,通用內部錯誤)時,這是 Meta 端的暫時性故障。Ayrshare 會自動重試發佈,最長約 50 秒,然後才回傳該錯誤,回應中會設定 retryAvailable: true,但不會設定 relink: true —— 重新連結帳號無法解決這種情況。當 Meta 回傳 fbtrace_id 時,該值會包含在 details 中:
2207085 子情況,請於幾分鐘後重試發佈 —— 這是 Meta 端的狀況,通常會自行恢復,重新連結帳號並無法解決。僅當錯誤持續超過 24-48 小時時,才提示使用者到 Social Accounts 中取消連結並重新連結 Instagram 帳號,授與所有要求的權限,或攜帶 details 中的 fbtrace_id 聯絡 Meta 支援。對於其他帳號狀態錯誤,請確認 Instagram 帳號在 Meta 上處於良好狀態後再重試。
可重試 (Retry Available)
有時社群網路會發生無法回復的錯誤,例如伺服器問題,即使經過多次重試呼叫最終仍失敗。 在這些情況下,我們的系統會判斷該錯誤是否可重試;如可重試,retryAvailable 欄位會為 true。
Instagram Reels 音訊錯誤
這些錯誤碼涵蓋使用instagramOptions.audioConfiguration 為 Instagram Reel 附加音樂,以及音訊搜尋與音訊查詢端點。
錯誤碼 518 會出現在
postIds[].warnings[],而不是 errors[]。 Instagram 每個 Reel 只允許一首曲目,因此當同時傳送 audioConfiguration 與 audioName 時,audioConfiguration 會勝出,audioName 會被捨棄。回應仍是 status: "success" 且 HTTP 200 —— 請將 518 視為資訊性內容,不要因它而判定失敗。該警告巢狀放在該平台的 postIds 項目上,而非最上層,並帶有 feature: "audioName"。音量驗證回報的是通用的
101,而非專屬錯誤碼。 audioVolume 與 videoVolume 必須是介於 0 到 100 的整數。小數、像 "80" 這樣的數字字串、超出範圍的數字,或明確的 null,都會在呼叫 Instagram 之前回傳 code: 101,並在 details 中指明該界限。請省略該欄位,而不要傳送 null。Automation Private-Reply(留言 DM)錯誤
這些錯誤碼會出現在留言觸發的自動化(comment_keyword)上,代表承載該 DM 的 private reply 無法傳送。它們會以活動列 status: "failed" 呈現,原因記在 actionResults[].errorDetails。
這些錯誤都不會被自動重試 — Instagram 的 Send API 沒有冪等性金鑰,自動重試可能會導致同一則 DM 被送達兩次。處理方式因錯誤碼而異(請見下方 動作):多數屬於該特定留言的永久性錯誤;492 需要重新連結帳號;493 則會在每小時上限重置後自行清除。
Code 491 涵蓋 Instagram 未加以區分的多種原因,而 490 是狹義的例外。 Instagram 對以下情況回傳同一個共享錯誤:留言超過 7 天、留言已收到回覆(每則留言僅能有一次 private reply)、留言已被刪除、以及留言者封鎖了訊息請求。以上皆會回報為
491。490 只會在較狹義的情況下回報:Instagram 直接將該留言 ID 判定為無效,而非回傳共用的錯誤桶 — 因此已刪除的留言可能會回報為 490 或 491,取決於 Instagram 回傳哪一個。由於 API 不區分這些情況,請務必檢視 errorDetails:其中攜帶 Instagram 自身的措辭,通常會較明確地指出原因。Code
489 保留但目前不使用。 該編號保留給「此留言已有回覆」的情境,但 Instagram 目前並未將此情況以獨立訊號揭露 — 該情境現行會回報為 491。此處列出僅是為了避免編號被再利用。真正過期或失效的連結不在此範圍內。 若已儲存的 Instagram 憑證已過期,活動列會顯示
status: "auth_error" 而非 failed,正確的處理方式是重新連結帳號。除 492(缺少權限,需重新連結帳號以授予)之外,上方這些代碼皆為留言層級的狀況,絕不代表需要「重新連結」。GET /automations/:id/activity 所回傳的內容。Instagram 的原因位於 actionResults[].errorDetails:
details:
errorDetails 攜帶的字串,會與封裝中 details 攜帶的字串相同。
動作:
- 490、491、495 — 屬於單一留言的狀況。它們無法針對該特定留言恢復,重試也無法改善;下一則新留言仍會正常觸發自動化。請閱讀
errorDetails以取得 Instagram 給出的原因。 - 492 — 重新連結 Instagram 帳號,授予所有要求的權限。這是帳號層級的修復方式,否則會影響每一則留言。
- 493 — 除了等待之外無需採取行動;每小時上限會自動重置。此錯誤不會被自動重試,因此該留言的 DM 不會被送出。
- 494 — 屬於內部設定錯誤,並非客戶端可處理的情況。若持續發生請聯絡支援。
sent 狀態並不保證訊息已送達。 與上述失敗情況不同,即使 Instagram 接受了 private reply(status: "sent"),若接收者的 Instagram Message requests 設定封鎖陌生人,該訊息仍可能被靜默地捨棄 — 此情況完全不會產生任何錯誤碼。請參閱 Automation DM Sent but Not Delivered。Thread 與媒體選項錯誤
當某個選項無法套用到貼文時,就會回傳以下錯誤碼 — 最常見於 X Thread 或 Threads thread,因為你傳送的選項會套用到整個 thread。182— 影片不符合時長要求。 影片短於該社群網路的最短時長,或長於其最長時長。 回應中會列出影片的實際時長,以及所套用的最短與最長時長,比較這三者即可確認你觸及 的是哪個界限。在 X 上,標準範圍為 0.5 到 140 秒(2 分 20 秒);若要發布更長的影片, 請設定longVideo: true,對於已獲 X 核准長影片的帳號,上限會提高到 4 小時。其他社群網路各有自己的限制 — 請參閱你要發布 之社群網路的媒體規範。101— 參數缺失或不正確。 在 Threads 上,當從 Meta 尚未賦予地區限制資格的帳號傳送allowCountries時會回傳此錯誤碼。 貼文或 thread 的任何部分都不會被發布。在傳送該選項之前,請先檢查 /user 上的isEligibleForGeoRestrictions。111— X 拒絕了貼文。 這是沒有更明確錯誤碼的 X 端失敗的通用錯誤碼,因此請閱讀 回應中的details— 它攜帶 X 自己的訊息,能告訴你失敗的原因。一個常見原因是帳號 無權使用的選項,例如在沒有 X Subscriptions 的情況下使用subscribersOnly,或在沒有 X Premium 的情況下於單一貼文上使用longPost;此時 請移除該選項或檢查帳號的權限。連線失敗與其他 X 端錯誤也會以111呈現,這類情況值得 重試,而不需要更改你的請求。請注意,longPost在 thread 上不會造成111— 在 thread 上它會被忽略並附帶一則 警告,且 thread 會照常發布。請參閱長貼文。275— 貼文過長,無法以 thread 發布。 拆分文字後產生的貼文數超過了 30 則的上限。 請縮短文字,或將其拆分成多個獨立的 thread。以\n\n加入你自己的 thread 分隔在這裡沒有幫助 — 每個分隔 都會產生另一則貼文,因此可能讓數量進一步超過上限。
你的帳號無法使用的選項會讓整則貼文失敗,而不是被忽略。對 thread 而言,這代表 thread 的
任何部分都不會被發布 — 已經發出的部分會自動為你刪除。刪除是盡力而為:如果社群網路拒絕
刪除,該部分可能仍維持發布狀態,因此請檢查該 thread 並移除任何殘留的內容。先前這些選項
中有一部分會在 thread 上被靜默地捨棄,thread 則會在未套用它們的情況下發布。
Link Session 錯誤
錯誤碼 501 到 513 屬於社群連結:以建立 Link Session 建立連結,以及開啟連結。它們帶有"action": "link session"。本頁的其他 500 系列錯誤碼與此
無關——514 到 518 是 Instagram Reels 音訊。
請比對數字的
code,而不是訊息文字——訊息文字可能變動或被翻譯。
**你的頁面能聽到其中哪些。**設定了 origin 之後,連結彈出視窗會向你的頁面傳送
連結完成事件,513 可以以 connect:error 的形式
這樣送達。501、502 與 503 不行:失效的連結會在頁面得知該把事件送到哪裡之前就被拒絕,
因此你的使用者會在畫面上看到原因,而你的頁面會在他們關閉視窗時聽到 connect:cancelled。
要區分這三者,請輪詢取得 Link Session。504 到 510 是對
POST 本身的拒絕,永遠不會以事件的形式送達;511 與 512 則是在社群網路回呼期間發生的,
因此會在那裡呈現,而不是在你的頁面上。
X/Twitter BYO Key 錯誤
以下錯誤碼專屬於 X/Twitter BYO(Bring Your Own)金鑰的操作: Code 272 - 無法驗證 BYO Twitter 身份 (HTTP 400) Ayrshare 無法使用你的 BYO consumer key 與連結時儲存的 OAuth token 確認你的 X/Twitter 身份。回應格式會因觸發的呼叫而異,兩種格式都對應到以下三個子情況。請以擁有該 BYO Developer App 的帳號登入 x.com 以確認實際情況。 貼文路徑會回傳精簡的回應:details 欄位:
details 若存在,會反映 X 端的提示,是判斷屬於下列哪個子情況最可靠的單一線索。
帳號遭停權。 登入 x.com 會顯示停權通知。動作: 聯絡 X 支援。在 X 恢復帳號之前,重新連結無法恢復存取權限。
帳號被鎖定。 登入 x.com 會出現解鎖挑戰(CAPTCHA、電話驗證等)。動作: 於 x.com 完成解鎖挑戰後再重試請求。不需要重新連結。
身份或金鑰不符。 你的 X 帳號在 x.com 狀態正常,但你的 BYO consumer key 屬於的 X Developer App 與連結時儲存的 OAuth token 不同。動作: 於 Social Accounts 重新連結 X,並使用擁有該 BYO Developer App 的相同 X 帳號授權。
Code 364 — X 速率限制 (HTTP 429)
X 對使用你的 BYO 金鑰發出的請求進行了節流。這是 Ayrshare 共用的速率限制錯誤碼,現在也涵蓋 X 留言讀取路徑:當 X 對讀取施加速率限制時,Get Comments 會回傳此錯誤碼,而先前則會回傳空的留言清單。
code: 416,因此 416 並不限於發佈文字或取得分析資料。上傳會在貼文發佈前失敗,且不會重試——在帳號有點數之前,任何重試都不會成功。
x-access-level: read,確認你的 Access Token 是以唯讀權限產生。
動作: 在 X Developer Console 中,將 app 權限更新為 Read and write and Direct message,然後在 Keys and tokens 重新產生 Access Token。新 token 會繼承更新後的權限。詳情請參閱 X BYO Key 設定指南。
Code 419 - 缺少 BYO 憑證 (HTTP 400)
X/Twitter 操作需在請求標頭中提供 BYO API 憑證。當兩個標頭皆缺失,或成對中僅提供其中之一時,Ayrshare 皆會回傳 code 419。message 字串會因缺少的標頭而不同。
當 X-Twitter-OAuth1-Api-Key 與 X-Twitter-OAuth1-Api-Secret 皆缺失時:
X-Twitter-OAuth1-Api-Key 與 X-Twitter-OAuth1-Api-Secret。若你只提供其中一個而未提供另一個,請求會以相同錯誤碼被拒絕。完整的標頭清單請見 X BYO Keys Header Reference。
Code 423 — 舊版 X/Twitter OAuth 已不再支援 (HTTP 403)
當 X/Twitter 請求仍依賴舊版(非 BYO)OAuth 流程時回傳,該流程已不再支援。X API 存取現在需要透過請求標頭提供你自己的 X Developer App 憑證。
X-Twitter-OAuth1-Api-Key 與 X-Twitter-OAuth1-Api-Secret 標頭。完整設定步驟請見 X BYO Key 設定指南。
內文優化錯誤
Code 441 — 內文優化失敗 (HTTP 502) 當在準備貼文時,某個或多個平台的內文優化(例如shortenLinks)失敗時回傳。每個受影響的平台會以 source: "handlePostAdditions" 與 code: 441 出現在 errors 陣列中。
當只有部分平台失敗時,其他平台仍會成功發布,其結果會出現在 postIds 中。此時最上層的 status 為 "error",但 postIds 不為空——客戶端應將 status 與 errors[] 視為互補而非互斥。
code: 441 與 HTTP 502,且不會建立任何貼文:
- 若
postIds不為空(部分平台已發布成功),請勿重新提交完整平台集合——這會在成功的平台上重複發文。應檢視errors[]找出失敗的平台,僅針對這些平台重試請求,或依賴你自己的冪等重試流程。 - 若
postIds為空或不存在(在排程/發布時全部失敗),可安全地重試整個請求。 - 若失敗持續發生,請去除優化旗標後再發布(例如移除
shortenLinks)或聯絡支援。
媒體抓取/爬蟲存取錯誤
Code 499 — Ayrshare 媒體探測暫時無法使用 (HTTP 503) 當 Ayrshare 無法完成發文前的媒體檢查時回傳——因為內部媒體探測服務無法連線或回應無效。這是 Ayrshare 服務端的故障,並不代表你的媒體 URL、CDN、user-agent 規則或robots.txt 設定有誤。此錯誤帶有 retryAvailable: true;請稍後針對失敗的平台重試。若多平台請求已部分成功,僅針對 errors[] 中列出的平台重試,以避免重複發文。
mediaUrls、無法讀取的媒體,以及部分網路上傳/抓取失敗。請先檢視回傳的 details。若為存取失敗,請確認 URL 可公開存取、在發布過程中保持有效期夠長,且未封鎖遠端請求。/media/urlExists 僅執行 HEAD 可達性檢查;該處的成功結果並不保證更深入的發文前媒體檢查或社群網路的爬蟲能下載並處理該檔案。當具體失敗原因是 Ayrshare 自身的探測服務無法使用時,你會收到可重試的 code 499,而不是 code 164。
Code 440 — 社群網路無法下載媒體 (HTTP 400)
當平台的發布爬蟲無法下載你提供的 mediaUrl 時回傳——最常見原因是 robots.txt 或 WAF/防機器人規則阻擋爬蟲(例如 Meta 的 facebookexternalhit)。details 字串來自上游平台,通常是 Meta/Instagram 的 error 2207052 文字。
details 字串通常包含 "Restricted by robots.txt" 或 "HTTP error code 403"。Code 138 也用於長寬比/格式問題以及其他一般性 Instagram 錯誤,因此媒體抓取變體可透過 details 字串辨識。
mediaUrl 同時發布至兩個平台時,Threads 遇到與 code 440/138 相同的媒體抓取問題。Threads API 不會回傳 detail 字串,因此通常需要透過同一次發布中同時出現的 Instagram 440 或 138 來診斷。
robots.txt 範例與驗證指令。
Threads 媒體尚未就緒
Code 522 — Threads 媒體尚未準備好發布 (HTTP 400) Ayrshare 嘗試發布貼文時,Threads 尚未完成貼文的準備。Threads 可能會在實際接受發布的幾秒鐘前就回報貼文已就緒。對於一則 Threads 貼文,Ayrshare 會在多部分 thread 的所有部分中合計等待並重試最多 30 秒,之後才回傳此錯誤,因此現在大多數這類貼文都能順利發布,不會出現任何錯誤。這通常是 Threads 端的暫時性問題,並非你的內容所致。 Threads 留言、回覆與首則留言也會獲得相同的等待(首則留言會在貼文發布後另外獲得 30 秒),但它們不會回傳 code 522。對於多部分 thread,code: 522 物件並不直接位於 errors 中:它是 Threads 錯誤中 posts 陣列的最後一個項目,且上述 HTTP 400 狀態僅適用於單則 Threads 貼文。noAutoRetry: true 只會阻止 Ayrshare MCP 伺服器自行重試該貼文;你仍然可以重試。
postIds。若沒有任何內容發布,請使用 retry post 端點重試貼文。若同一則貼文中的其他平台已成功發布,請改為僅向 Threads 送出新貼文:retry post 會將原始 payload 重新傳送至每一個平台,這會讓已成功的平台再次發布相同內容。
多部分 thread: postIds 為空並不能證明 thread 的任何部分都未上線。當後續部分失敗時,Ayrshare 會移除已發布的部分,但若移除失敗,該部分會保留在 Threads 上。在重試多部分 thread 之前,請檢查 Threads 帳號並刪除仍存在的部分,否則重試會再次發布它們。
Facebook Analytics 速率限制
Code 444 — Facebook 粉絲專頁分析速率限制 (HTTP 429) 當 Facebook 粉絲專頁在分析端點上超過 Meta 的每專頁速率限制時回傳。底層的 Meta 錯誤為80001(「There have been too many calls to this Page account.」)。粉絲專頁仍為已連結狀態且可繼續發布——只有該專頁的分析請求被節流。
當在 /history/facebook 或分析回應中偵測到單一貼文的節流時,每個受影響的貼文會在 facebook.code 帶有 code: 444 與 errCode: 80001:
Meta 身份驗證
Code 326 — 需要 Meta 身份驗證 (HTTP 403) 當 Meta 要求所連結帳號進行額外身份驗證後才會接受請求時回傳。此錯誤適用於各 Meta 平台——Facebook、Instagram、Facebook Groups、Threads 與 Messenger。重新連結帳號無法解決此問題;驗證必須在 Meta 端完成。Facebook 社群守則封鎖
Code 249 — Facebook 社群守則封鎖 (HTTP 400) 當 Facebook 依其社群守則(Community Standards)封鎖貼文時回傳。封鎖可能套用在 Facebook 帳號或粉絲專頁上,也可能套用在貼文本身。Facebook 對這兩種情況使用相同的底層錯誤,且不會說明屬於哪一種。實務上,封鎖最常套用在帳號或粉絲專頁上,因此改寫或重新提交內容往往沒有幫助。與 Facebook 帳號限制(code 476)相同,這是 Meta 端的執法結果,此錯誤不可重試,也不會帶retryAvailable 旗標。首次違規時,帳號仍維持連結至 Ayrshare 的狀態,無需重新連結,而且重新連結也無法解除封鎖。重複違規的情況則不同,請見下文。
Facebook 不會透過 API 回傳具體原因,客戶必須直接前往 Facebook 的 Account Status 頁面查看原因並申訴。當 Facebook 提供其原文時,Ayrshare 會於 details 欄位呈現。當偵測到封鎖時,Ayrshare 也會傳送通知 email 給帳號擁有者。
若同一個使用者檔案(User Profile)重複違反社群守則,Facebook 帳號將與 Ayrshare 解除連結,且該 User Profile 會遭停權。
code 的值 249,而不是 message 文字。message 的措辭日後可能會調整,而錯誤碼則維持不變。
動作: 登入 Facebook,點擊右上角的個人檔案照片,開啟「Help」區段並選擇 Account Status(帳號狀態)。Facebook 的支援助手會在該處顯示具體原因(API 不會回傳此資訊)並提供申訴。請勿提示使用者重新連結帳號,因為重新連結無法解除帳號或粉絲專頁層級的封鎖。完整的疑難排解指南請參閱 Facebook 或 Instagram 帳戶遭限制。
Facebook 帳號限制
Code 476 — Facebook 帳號限制 (HTTP 400) 當發布至 Facebook 因 Meta 已對帳號設下限制而失敗時回傳(Meta error subcode2424009 與 1404078,或當錯誤未帶 subcode 時 Meta 的限制措辭)。這是帳號層級的限制,不是暫時性發布故障——此錯誤不可重試,也不會帶 retryAvailable 旗標。以相同貼文再次提交在該限制與 Meta 之間未解決前不會成功。帳號仍為連結至 Ayrshare 的狀態,無需重新連結。
Meta 不會透過 API 回傳具體限制原因,客戶必須直接前往 Meta 的 Account Status 頁面查看原因並申訴。當 Meta 提供其原文時,Ayrshare 會於 details 欄位呈現。當偵測到限制時,Ayrshare 也會傳送通知 email 給帳號擁有者。
圖片格式轉換錯誤
Ayrshare 會在發布至不接受 WebP、HEIC、HEIF 與 AVIF 的平台前自動將這些圖片轉換為 JPEG(Instagram、LinkedIn、TikTok、Google My Business、Threads 與 Snapchat 針對 WebP;所有平台針對 HEIC、HEIF 與 AVIF)。轉換會在發送時透明執行。以下三個錯誤只有在轉換流程本身無法完成時才會觸發;若原始圖片已為支援的格式,則不會嘗試轉換,這些錯誤碼也不會出現。 Code 450 — 圖片格式轉換失敗 (HTTP 400) 圖片已下載,但無法重新編碼為 JPEG。最常見原因是原始檔案損毀、容器內部含有非預期的格式,或圖片超過轉換的大小上限。mediaUrl 以確認可顯示。如果可以,請重新匯出為乾淨的 JPEG 或 PNG 檔案後重試貼文。
Code 451 — 為了轉換而下載圖片失敗 (HTTP 400)
轉換流程無法抓取原始圖片。常見原因包括來源回傳 4xx/5xx、網路逾時、重新導向鏈超過跳轉限制,或網址解析為非公開位址(被 SSRF 防護阻擋)。details 欄位若存在,會帶有底層原因字串。
mediaUrl 可公開存取(不需驗證、沒有 robots.txt 封鎖、透過 HTTPS 可解析)。若網址有重新導向,請確保最終目的地也為公開,且不在私有網路內。
Code 452 — 已轉換的圖片上傳失敗 (HTTP 500)
轉換成功,但 Ayrshare 無法將轉換後的 JPEG 暫存至暫存儲存桶。這是 Ayrshare 端的內部失敗,可以重試。
mediaUrl 與大致時間戳記。
YouTube 暫時性上傳錯誤
以下錯誤碼專門用於 YouTube 上傳失敗中通常屬於暫時性且可安全重試的情況。兩種回應都會包含retryAvailable: true,因此整合應依此布林值而非 HTTP 狀態碼進行分支判斷。
大多數以前針對 YouTube 上傳的 code: 176 回應,現在會改為導向 453(暫時性逾時)或 454(暫時性服務不可用),兩者皆帶有 retryAvailable: true。若你的整合是依 HTTP 500 過濾以重試 YouTube 上傳,請改為根據回應主體中的 retryAvailable 欄位過濾。
Code 453 — YouTube 上傳逾時 (HTTP 504)
當 Google 的 YouTube 匯入流程在接收上傳時逾時的情況下回傳。通常是暫時性的,會在一至兩分鐘內自行恢復。
retryAvailable 欄位(而非 HTTP 狀態)判斷是否可重試。你也可以使用 retry post 端點以相同 payload 重新提交。
Code 454 — YouTube 上傳服務暫時無法使用 (HTTP 503)
當 YouTube 上傳端點回傳 5xx 狀態,或至 YouTube 的連線在 socket 層被重設或逾時(ECONNRESET、ETIMEDOUT、ESOCKETTIMEDOUT)時回傳。這些皆為暫時性狀況。
retryAvailable 欄位(而非 HTTP 狀態)判斷是否可重試。
YouTube 縮圖錯誤 Code 307
當自訂 YouTubethumbNail 無法套用時,會回傳 code 307。當影片本身發布成功時,此錯誤不會讓貼文失敗——YouTube 結果仍為 status: "success",並在 warnings 陣列中以附加方式呈現失敗(feature: "thumbnail"、code: 307)。為了向後相容,仍會保留舊版的 thumbnail 子物件。
最常見原因是未驗證的 YouTube 頻道。當頻道未完成電話驗證時,YouTube 會回傳上游 403 與一般訊息 "The authenticated user doesn't have permissions to upload and set custom video thumbnails"。該措辭看起來像 OAuth 問題,但實際上幾乎總是驗證問題,因此請先確認頻道驗證。重新連結 YouTube 帳號則為次要原因。
warnings 條目呈現(最上層 status 仍為 "success")。無論在什麼時機偵測到問題都適用:
- 上傳前被攔截。 當發布前驗證能確定縮圖無效時(檔案類型錯誤、確認超過 2MB,或網址無法存取),Ayrshare 會略過縮圖,仍然發布影片,並在
warnings中回報精確原因——你可避免注定失敗的上傳嘗試,並得到比服務商更清楚的訊息。 - 上傳後被偵測到。 當失敗只有在 YouTube 處理請求時才偵測到(例如未驗證頻道的
403,或圖片過大時的413),影片已上線,失敗會在同一個warnings陣列中呈現。
status: "success" + warnings。
動作: 前往 https://www.youtube.com/verify 驗證你的 YouTube 頻道(電話驗證)。若頻道已驗證但縮圖仍失敗,請到 Social Accounts 取消連結並重新連結 YouTube 帳號並授與所有權限。完整疑難排解請見 YouTube Thumbnail Not Applied (Unverified Channel)。
Google Business Profile 授權錯誤
Code 519 — Google Business Profile 授權服務暫時無法使用 (HTTP 503) 當 Ayrshare 無法完成 Google 授權權杖更新時回傳——因為 Google 的權杖端點回應緩慢或回傳暫時性故障。在回傳此錯誤碼之前,系統會自動重試更新,且回應會帶有retryAvailable: true,因此整合可以根據此布林值而非 HTTP 狀態碼進行分支判斷。帳號仍保持連結——這是 Google 授權服務端的暫時性狀況,並非連結中斷。
每個 Google Business Profile 操作都會先更新授權,因此任何操作都可能回傳此錯誤碼——發布貼文、讀取貼文歷史、更新地點資料、擷取已連結帳號、列出評論,以及回覆評論。
這些路徑上大多數先前的 code: 227 回應,現在會改為導向 519 並帶有 retryAvailable: true。Code 227 會要求使用者重新連結帳號,但這從未能解決暫時性的更新失敗——授權本身自始至終都是完好的。若你的整合是依 227 過濾以提示重新連結 Google Business Profile,請改為根據回應主體中的 retryAvailable 欄位進行分支判斷,並以退避方式重試。
details 會帶有 Google 回報的原因,或——當更新在本地逾時且 Google 未回傳任何回應主體時——已嘗試次數與所耗時間的摘要。
動作: 以指數退避重試請求。請根據回應主體中的 retryAvailable 欄位(而非 HTTP 狀態)判斷是否可重試。
Pinterest AI 揭露警告
Code 521 — 未套用 Pinterest AI 揭露 (HTTP 200) 警告,並非錯誤。 當pinterestOptions.aiDisclosures 無效時回傳,例如未知的值或大小寫錯誤。透過 REST API 時,非字串陣列的值也會回傳 521。Pin 仍會發布,但 Ayrshare 不會向 Pinterest 傳送任何 AI 揭露。MCP 伺服器與 GraphQL API 會先檢查值的型別,因此格式錯誤的值(例如包含數字的清單)會在發布前即於該處被拒絕。此警告會出現在 Pinterest 項目的 postIds[].warnings[],而不是 errors[],並帶有 feature: "pinterestOptions.aiDisclosures"。可接受的值為 AI_MODIFIED 與 SYNTHETIC_PERFORMER。
Reddit 發布錯誤
Code 442 — Reddit 遭到 subreddit 封鎖 (HTTP 400) 當帳號已被目標 subreddit 禁止發文時回傳。此錯誤不可重試——原樣重新提交貼文不會成功。訊息會包含受影響的 subreddit 名稱(例如r/news)。
r/news)。
內容審核錯誤
Code 438 — 內容審核輸入被拒 (HTTP 400) 當 AI 服務商拒絕所提供的輸入時,由POST /validate/moderation 回傳——例如不支援的檔案類型。這是請求輸入層面的問題,並非暫時性處理失敗。
請對照 code 438 與 code 331。Code 331 涵蓋相同的內容審核情境,但代表服務商端的實際處理失敗(HTTP 500,訊息「There was an issue with the AI processing. Please try again.」)。Code 331 為可重試的暫時性伺服器端失敗,而 code 438 表示輸入本身被拒絕,必須先更正才能重試。
LinkedIn 授權更新錯誤
Code 524 — LinkedIn 權杖更新遭拒 (HTTP 500) 當 LinkedIn 因應用程式的 LinkedIn 設定問題(而非使用者帳號問題)拒絕更新授權時傳回。使用者的 LinkedIn 連線仍然有效,因此重新連結無法解決此問題。回應不包含resolution.relink 欄位,並帶有 retryAvailable: false,因為重試也無法解決此問題。
任何會先更新授權的 LinkedIn 操作都可能傳回此代碼,例如在存取權杖過期後發布貼文。
如果 LinkedIn 因暫時性原因持續更新失敗,Ayrshare 會重試,然後改為傳回 code 119(「There was an issue connecting with LinkedIn. Please try again.」)。Code 119 可以安全地稍後重試;code 524 無法透過重試解決。
LinkedIn Analytics 錯誤
Code 475 — 重新連結 LinkedIn 個人檔案以取得分析 (HTTP 403) 當個人(member)LinkedIn 檔案是在 member analytics 上線之前完成連結時,由POST /analytics/post 與 POST /analytics/social 回傳。這些檔案缺少 LinkedIn member analytics 的 scope(r_member_postAnalytics、r_member_profileAnalytics),因此 LinkedIn 會拒絕分析請求。發布本身不受影響。
475 約 5–10 分鐘後才能成功取得分析。
TikTok 留言錯誤
Code 288 — TikTok 留言延後/貼文仍在處理中 (HTTP 400) TikTok 是非同步處理影片,因此剛發布的貼文id 在 TikTok 的 post.publish.publicly_available webhook 解析出實際 video id 之前會是 "pending"。針對仍在處理中的貼文(或 id 為 "failed" 的貼文)發送 get-comments、留言或回覆請求時,會在呼叫 TikTok 之前被拒絕,並回傳 code 288 而非一般性錯誤。
tikTokPublished Scheduled Action webhook,或輪詢 /history 直到貼文 id 是解析後的數字 video id。第一則留言在貼文解析後會自動發布,因此無需重試。若貼文為 "failed",訊息則會標示影片發布失敗且該動作不會執行。
已過期或無法使用的 Story 錯誤
Code 485 — Instagram / Facebook Story 留言與 Instagram Story 分析(作為代表性錯誤碼時對應 HTTP 404) Story 可能在其可用視窗結束後過期或變為無法使用。過了該視窗後,就無法取得留言或洞察資料。Code485 用於識別:
- 來自 get-comments 的已過期或無法使用的 Instagram 與 Facebook Story 分支;以及
- 來自
POST /analytics/post的已過期或無法使用的 Instagram Story 分支。
485 的涵蓋範圍內。用戶端應以數值 code 比對,而非以完整訊息文字比對,因為訊息文字可能會有差異或被翻譯。
在多平台讀取中,若至少有另一個平台成功,失敗的分支會出現在最上層的 errors[] 陣列中,而正常的平台會照常回傳。整體回應為 HTTP 200,最上層 status: "partial"(留言相關請參閱 多平台讀取與部分成功,分析相關請參閱 analytics)。
Get Comments 部分成功範例
Post Analytics 部分成功範例
status: "error",並包含完整的 errors[] 陣列。代表性的 code 485 對應到 HTTP 404;其他代表性代碼則使用各自的 HTTP 對應關係。
動作: 將 code 485 視為所要求的 Story 留言或洞察資料無法取得的訊號。請以代碼比對,而不要從訊息文字推論為永久失敗、是否可重試或帳號連結狀態。
錯誤訊息翻譯
API 錯誤訊息回應可以自動翻譯成你選擇的語言。 若你想直接以使用者偏好的語言顯示錯誤,這將非常實用。 若你想選擇社群連結頁面的語言,請參閱該連結。 於標頭中加入:Language_Code 為可用的語言代碼之一。
例如,下列會將錯誤翻譯為法文。