Ayrshare 錯誤碼 - Ayrshare API Documentation

REST API 在必要時會於回應中包含錯誤列表。

錯誤的 HTTP 狀態碼為 400、401、402、403、404、429、500、502、503 或 504；成功時狀態碼為 200。詳情請見此處。

每個 API 呼叫可能因為請求本身或社群網路端遇到的問題而回傳不同的錯誤。錯誤回應會包含此次 API 呼叫失敗的詳細資訊。例如，被 Twitter 與 Facebook 判定為重複的貼文會回傳下列回應：

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 110,
      "message": "Status is a duplicate.",
      "post": "Today is a great day",
      "platform": "twitter"
    },
    {
      "action": "post",
      "status": "error",
      "code": 107,
      "message": "Facebook Error: This status update is identical to the last one you posted.
        Try posting something different, or delete your previous update.",
      "platform": "facebook"
    }
  ],
  "postIds": [],
  "id": "6APU4qqI7XO7JM3BOy6B"
}

請注意：

errors 欄位包含錯誤陣列，每個發生錯誤的社群網路各對應一筆。
action 代表所回傳錯誤的類型。
最上層的 status 欄位在 API 呼叫失敗時為「error」。例如，對於 /post 呼叫，若所有社群網路的貼文皆成功，status 欄位會是「success」；否則為「error」。
code 欄位為 Ayrshare 的參考錯誤碼。
message 欄位為錯誤的具體細節。

處理錯誤

你應該處理任何錯誤回應並採取相對應的動作。發生錯誤的情況為：

回應的狀態碼不是 200
JSON 回應的 status 為 error

例如，若你的使用者移除了 Facebook 連結——他們更改密碼或撤銷了 Ayrshare 的存取權限——發布時會回傳以下 400 Bad Request 回應：

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 161,
      "message": "Facebook authorization error. This can occur if your Facebook security changes. Try unlinking and re-linking Facebook or contact us for assistance.",
      "platform": "facebook"
    }
  ],
  "postIds": [],
  "id": "gh7SyTpeD2CQAMxWk3oh",
  "post": "A great Facebook Posts"
}

你可以採取的動作包括透過儀表板、簡訊或 email 通知使用者。另一個範例是，若發布到 Instagram 的圖片尺寸或比例錯誤，會回傳 400 Bad Request：

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 138,
      "message": "Instagram Error: There was an issue posting to Instagram. The submitted image with aspect ratio ('1440/2158',) cannot be published. Please submit an image with a valid aspect ratio.",
      "platform": "instagram"
    }
  ],
  "postIds": [],
  "id": "Jxe2nMM3FmEvMXFSY3g4",
  "post": "Is this a good image?"
}

你可以採取的動作是以正確比例重新提交圖片。

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 呈現。

{
  "status": "error",
  "errors": [
    {
      "action": "rate limit",
      "status": "error",
      "code": 435,
      "message": "Instagram rate limit reached. Please wait before retrying your post.",
      "details": "Retry-After: 3600",
      "platform": "instagram"
    }
  ]
}

動作： 等待速率限制的時間視窗重設後再重試。當 Meta 提供 Retry-After 標頭時，其值（單位為秒）會透傳到 details 欄位——至少等待該秒數後再重新提交。 Code 436 — Instagram 媒體處理逾時 (HTTP 400) Instagram 處理上傳媒體的時間過長。可能發生於大型影片檔或 Meta 伺服器高負載時期。

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 436,
      "message": "Instagram media processing timed out. Please try posting again.",
      "retryAvailable": true,
      "platform": "instagram"
    }
  ]
}

動作： 使用 retry post 端點重試貼文。若問題持續發生，請嘗試縮小媒體檔案。 Code 447 — Instagram Trial Reels：缺少 graduationStrategy (HTTP 400) 當 /post 請求提供了 instagramOptions.trialParams，但 graduationStrategy 為缺失、null 或空字串時回傳。Trial reels 需要明確的 graduation strategy——請參閱 Trial Reels。

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 447,
      "message": "Instagram trial reels require instagramOptions.trialParams.graduationStrategy (\"MANUAL\" or \"SS_PERFORMANCE\").",
      "platform": "instagram"
    }
  ]
}

動作： 將 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 個字元）以便偵錯。

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 448,
      "message": "Invalid Instagram graduationStrategy. Must be \"MANUAL\" or \"SS_PERFORMANCE\".",
      "details": "Received: manual",
      "platform": "instagram"
    }
  ]
}

動作： 將 graduationStrategy 精確地送出為 "MANUAL" 或 "SS_PERFORMANCE"（大寫、字串型別）。 Code 449 — Instagram Trial Reels：不相容的媒體 (HTTP 400) 當媒體或貼文型式不符合 trial reel 的要求時回傳。Trial reels 必須是單一 .mp4 或 .mov 影片——輪播（多個 URL）、限時動態（instagramOptions.stories: true）以及非影片副檔名都會被拒絕。details 欄位會指出實際觸發的子情況。

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 449,
      "message": "Instagram trial reels must be a single video (.mp4 or .mov) — carousels and stories are not supported.",
      "details": "Carousels are not supported.",
      "platform": "instagram"
    }
  ]
}

動作： 提交單一 .mp4 或 .mov 影片網址，且不要帶 stories: true 旗標。移除多餘的 mediaUrls 條目；或者如果你原本要發一般輪播／限時動態，請移除 trialParams。 Code 258 — Instagram 帳號狀態錯誤 (HTTP 400) 一般性的 Instagram 帳號狀態失敗，基礎訊息為「Error with Instagram.」。此錯誤在 Meta 因所連結的 Instagram 帳號狀態（而非貼文內容）拒絕請求時出現。

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 258,
      "message": "Error with Instagram.",
      "platform": "instagram"
    }
  ]
}

當底層的 Meta error_subcode 為 2207085 時，回應會額外設定 relink: true 與 retryAvailable: true，訊息也會指示使用者取消連結並重新連結 Instagram 帳號，並授與所有權限：

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 258,
      "message": "Error with Instagram. Please unlink and relink your Instagram account, granting all permissions, then retry.",
      "relink": true,
      "retryAvailable": true,
      "platform": "instagram"
    }
  ]
}

動作： 針對 2207085 子情況，請提示使用者到 Social Accounts 中取消連結並重新連結 Instagram 帳號，授與所有要求的權限，然後重試貼文。對於其他帳號狀態錯誤，請確認 Instagram 帳號在 Meta 上處於良好狀態後再重試。

可重試 (Retry Available)

有時社群網路會發生無法回復的錯誤，例如伺服器問題，即使經過多次重試呼叫最終仍失敗。在這些情況下，我們的系統會判斷該錯誤是否可重試；如可重試，retryAvailable 欄位會為 true。

{
  "retryAvailable": true
}

你可以用相同的 payload 重試呼叫。若為貼文，可使用 retry post 端點。

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 以確認實際情況。貼文路徑會回傳精簡的回應：

{
  "status": "error",
  "code": 272,
  "message": "Failed to verify BYO Twitter identity",
  "platform": "twitter"
}

分析路徑則會回傳較長且更具說明性的訊息，並可能包含帶有 X 原始錯誤字串的 details 欄位：

{
  "action": "post",
  "status": "error",
  "code": 272,
  "message": "There is an issue authorizing your X/Twitter account. Login to x.com to verify your account status and then try unlinking Twitter and relinking on the social accounts page.",
  "resolution": {
    "relink": true,
    "platform": "twitter"
  },
  "details": "The user used for authentication is suspended"
}

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 416 — X 點數耗盡 (HTTP 402) 你的 X Developer 帳號未載入 API 點數。所有 X API 呼叫都需要點數。

{
  "status": "error",
  "code": 416,
  "message": "Your enrolled account does not have any credits to fulfill this request. Purchase credits at console.x.com.",
  "platform": "twitter"
}

動作： 前往 console.x.com → Billing → Credits 購買點數。即使只有 $5 也足以進行數百次 API 呼叫。 Code 417 — OAuth 1.0a App 權限 (HTTP 403) 你的 X Access Token 沒有執行所請求操作的正確權限。

{
  "status": "error",
  "code": 417,
  "message": "Your client app is not configured with the appropriate oauth1 app permissions. Set app to 'Read and write and Direct message', then regenerate your Access Token.",
  "platform": "twitter"
}

你也可能會看到回應標頭 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 皆缺失時：

{
  "action": "x_credentials_required",
  "status": "error",
  "code": 419,
  "message": "X/Twitter operations require your own API credentials. Missing: X-Twitter-OAuth1-Api-Key, X-Twitter-OAuth1-Api-Secret. Please provide your X Developer App credentials in the request headers. See https://docs.ayrshare.com/x-api-setup for setup instructions.",
  "resolution": {
    "docs": "https://docs.ayrshare.com/x-api-setup"
  },
  "platform": "twitter"
}

當僅提供成對中的一個時（例如只提供 key 而沒有 secret）：

{
  "action": "x_credentials_required",
  "status": "error",
  "code": 419,
  "message": "You provided X-Twitter-OAuth1-Api-Key but not X-Twitter-OAuth1-Api-Secret. OAuth 1.0a requires both. Missing: X-Twitter-OAuth1-Api-Secret. See https://docs.ayrshare.com/x-api-setup for setup instructions.",
  "resolution": {
    "docs": "https://docs.ayrshare.com/x-api-setup"
  },
  "platform": "twitter"
}

動作： 在每個 X 相關請求中同時送出 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 憑證。

{
  "status": "error",
  "code": 423,
  "message": "X (Twitter) API access now requires your own API credentials. Include X-Twitter-OAuth1-Api-Key and X-Twitter-OAuth1-Api-Secret headers in your request. Setup guide: https://docs.ayrshare.com/dashboard/connect-social-accounts/x-twitter-byo-keys",
  "platform": "twitter"
}

動作： 設定 X Developer App，並在每個 X 相關請求中送出 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[] 視為互補而非互斥。

{
  "status": "error",
  "errors": [
    {
      "platform": "twitter",
      "status": "error",
      "source": "handlePostAdditions",
      "code": 441,
      "message": "Caption enhancement failed for twitter. <underlying error>. Post was not sent to this platform."
    }
  ],
  "postIds": [
    {
      "status": "success",
      "id": "...",
      "postUrl": "...",
      "platform": "bluesky"
    }
  ],
  "id": "..."
}

若所有平台的優化皆失敗，回應會是最上層 code: 441 與 HTTP 502，且不會建立任何貼文：

{
  "status": "error",
  "action": "post",
  "code": 441,
  "message": "Caption enhancement failed. See error details for affected platforms.",
  "errors": [
    {
      "platform": "twitter",
      "status": "error",
      "source": "handlePostAdditions",
      "code": 441,
      "message": "Caption enhancement failed for twitter. <underlying error>"
    }
  ]
}

動作： 內文優化失敗通常是暫時性的（底層的縮網址或優化服務回傳錯誤）。

若 postIds 不為空（部分平台已發布成功），請勿重新提交完整平台集合——這會在成功的平台上重複發文。應檢視 errors[] 找出失敗的平台，僅針對這些平台重試請求，或依賴你自己的冪等重試流程。
若 postIds 為空或不存在（在排程／發布時全部失敗），可安全地重試整個請求。
若失敗持續發生，請去除優化旗標後再發布（例如移除 shortenLinks）或聯絡支援。

媒體抓取／爬蟲存取錯誤

Code 440 — 社群網路無法下載媒體 (HTTP 400) 當平台的發布爬蟲無法下載你提供的 mediaUrl 時回傳——最常見原因是 robots.txt 或 WAF／防機器人規則阻擋爬蟲（例如 Meta 的 facebookexternalhit）。details 字串來自上游平台，通常是 Meta/Instagram 的 error 2207052 文字。

{
  "status": "error",
  "errors": [{
    "action": "post",
    "code": 440,
    "message": "The social network could not download media from this URL (for example Instagram/Meta error 2207052). Ensure the file is publicly reachable by the platform's crawlers (e.g. facebookexternalhit), via media bucket's robots.txt file, not only in a browser.",
    "details": "Media download has failed.: The media could not be fetched from the provided URI...",
    "platform": "instagram",
    "status": "error"
  }],
  "postIds": [],
  "id": "..."
}

Code 138 — Instagram 媒體抓取被封鎖 (HTTP 400) 當上游回應比觸發 code 440 的情況更不具體時，Instagram 媒體抓取失敗會退回此錯誤碼。details 字串通常包含 "Restricted by robots.txt" 或 "HTTP error code 403"。Code 138 也用於長寬比／格式問題以及其他一般性 Instagram 錯誤，因此媒體抓取變體可透過 details 字串辨識。

{
  "status": "error",
  "errors": [{
    "retryAvailable": true,
    "status": "error",
    "code": 138,
    "details": "Media download has failed.: The media could not be fetched from the provided URI. Video download failed with: HTTP error code 403. Restricted by robots.txt",
    "action": "post",
    "platform": "instagram",
    "message": "Instagram Error: Instagram cannot process your post at this time. Please try your post again."
  }],
  "postIds": [],
  "id": "..."
}

Code 379 — Threads 發布錯誤 當 Threads 發布失敗時回傳。最常見原因為當你使用相同的 mediaUrl 同時發布至兩個平台時，Threads 遇到與 code 440／138 相同的媒體抓取問題。Threads API 不會回傳 detail 字串，因此通常需要透過同一次發布中同時出現的 Instagram 440 或 138 來診斷。

{
  "status": "error",
  "errors": [{
    "status": "error",
    "code": 379,
    "message": "Error posting to Threads.",
    "action": "post",
    "platform": "threads"
  }],
  "postIds": [],
  "id": "..."
}

動作： 完整的疑難排解請見 Meta 媒體爬蟲被封鎖，包含 robots.txt 範例與驗證指令。

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：

{
  "status": "error",
  "facebook": {
    "action": "rate limit",
    "status": "error",
    "code": 444,
    "errCode": 80001,
    "message": "Facebook Page has hit its per-Page rate limit on the analytics endpoint. Please wait a few minutes and retry.",
    "pageId": "...",
    "id": "..."
  },
  "httpErrorCode": 444,
  "lastUpdated": "...",
  "nextUpdate": "..."
}

動作： 等待數分鐘後再重試。Meta 的每專頁速率限制視窗通常會在一小時內自行解決，粉絲專頁端無需採取任何動作。請勿提示使用者重新連結帳號——這是 Meta 端的暫時性節流，並非授權失敗。

如果你之前將此情況視為 code: 161（「Facebook authorization error … unlink and re-link」），請更新整合，改為辨識 code: 444 並以退避重試，而不是啟動重新連結流程。此 161 分類已於 2026 年 4 月更正。

Meta 身份驗證

Code 326 — 需要 Meta 身份驗證 (HTTP 403) 當 Meta 要求所連結帳號進行額外身份驗證後才會接受請求時回傳。此錯誤適用於各 Meta 平台——Facebook、Instagram、Facebook Groups、Threads 與 Messenger。重新連結帳號無法解決此問題；驗證必須在 Meta 端完成。

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 326,
      "message": "Meta is requesting additional identity verification for this account. Complete it at https://www.facebook.com/business-support-home and then retry. Reconnecting the account will not resolve this.",
      "platform": "facebook"
    }
  ]
}

動作： 請帳號擁有者到 Meta Business Support 完成 Meta 的身份驗證後再重試。請勿提示使用者重新連結帳號——重新連結無法清除此要求。

Facebook 帳號限制

Code 476 — Facebook 帳號限制 (HTTP 400) 當發布至 Facebook 因 Meta 已對帳號設下限制而失敗時回傳（Meta error subcode 2424009 與 1404078，或當錯誤未帶 subcode 時 Meta 的限制措辭）。這是帳號層級的限制，不是暫時性發布故障——此錯誤不可重試，也不會帶 retryAvailable 旗標。以相同貼文再次提交在該限制與 Meta 之間未解決前不會成功。帳號仍為連結至 Ayrshare 的狀態，無需重新連結。 Meta 不會透過 API 回傳具體限制原因，客戶必須直接前往 Meta 的 Account Status 頁面查看原因並申訴。當 Meta 提供其原文時，Ayrshare 會於 details 欄位呈現。當偵測到限制時，Ayrshare 也會傳送通知 email 給帳號擁有者。

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 476,
      "message": "There is a Facebook restriction on your account. Log in to Facebook, click your profile picture (top-right), open the Help section and select Account Status. Meta's support assistant there surfaces the specific restriction reason (which the API doesn't return) and lets you appeal.",
      "details": "...",
      "platform": "facebook"
    }
  ]
}

動作： 登入 Facebook，點擊右上角的個人檔案照片，開啟「Help」區段並選擇 Account Status。Meta 的支援助手會顯示具體的限制原因並提供申訴。由於限制是由 Meta 在帳號層級強制執行，此錯誤碼不可重試——請勿為其建立自動重試邏輯；請先與 Meta 解決該限制。

圖片格式轉換錯誤

Ayrshare 會在發布至不接受 WebP、HEIC 與 AVIF 的平台前自動將這些圖片轉換為 JPEG（Instagram、LinkedIn、TikTok、Google My Business、Threads 與 Snapchat 針對 WebP；所有平台針對 HEIC 與 AVIF）。轉換會在發送時透明執行。以下三個錯誤只有在轉換流程本身無法完成時才會觸發；若原始圖片已為支援的格式，則不會嘗試轉換，這些錯誤碼也不會出現。 Code 450 — 圖片格式轉換失敗 (HTTP 400) 圖片已下載，但無法重新編碼為 JPEG。最常見原因是原始檔案損毀、容器內部含有非預期的格式，或圖片超過轉換的大小上限。

{
  "status": "error",
  "errors": [
    {
      "action": "image conversion",
      "status": "error",
      "code": 450,
      "message": "The image format could not be converted. The source image may be corrupt or inaccessible. Please verify the media URL and try again.",
      "platform": "instagram"
    }
  ]
}

動作： 直接在瀏覽器開啟原始 mediaUrl 以確認可顯示。如果可以，請重新匯出為乾淨的 JPEG 或 PNG 檔案後重試貼文。 Code 451 — 為了轉換而下載圖片失敗 (HTTP 400) 轉換流程無法抓取原始圖片。常見原因包括來源回傳 4xx/5xx、網路逾時、重新導向鏈超過跳轉限制，或網址解析為非公開位址（被 SSRF 防護阻擋）。details 欄位若存在，會帶有底層原因字串。

{
  "status": "error",
  "errors": [
    {
      "action": "image conversion",
      "status": "error",
      "code": 451,
      "message": "The image could not be downloaded for format conversion.",
      "details": "HTTP 403 from origin",
      "platform": "linkedin"
    }
  ]
}

動作： 確認 mediaUrl 可公開存取（不需驗證、沒有 robots.txt 封鎖、透過 HTTPS 可解析）。若網址有重新導向，請確保最終目的地也為公開，且不在私有網路內。 Code 452 — 已轉換的圖片上傳失敗 (HTTP 500) 轉換成功，但 Ayrshare 無法將轉換後的 JPEG 暫存至暫存儲存桶。這是 Ayrshare 端的內部失敗，可以重試。

{
  "status": "error",
  "errors": [
    {
      "action": "image conversion",
      "status": "error",
      "code": 452,
      "message": "An error occurred uploading the converted image. Please try again.",
      "platform": "tiktok"
    }
  ]
}

動作： 重試貼文。若在多次重試後錯誤仍持續發生，請聯絡支援並附上 mediaUrl 與大致時間戳記。

YouTube 暫時性上傳錯誤

以下錯誤碼專門用於 YouTube 上傳失敗中通常屬於暫時性且可安全重試的情況。兩種回應都會包含 retryAvailable: true，因此整合應依此布林值而非 HTTP 狀態碼進行分支判斷。大多數以前針對 YouTube 上傳的 code: 176 回應，現在會改為導向 453（暫時性逾時）或 454（暫時性服務不可用），兩者皆帶有 retryAvailable: true。若你的整合是依 HTTP 500 過濾以重試 YouTube 上傳，請改為根據回應主體中的 retryAvailable 欄位過濾。 Code 453 — YouTube 上傳逾時 (HTTP 504) 當 Google 的 YouTube 匯入流程在接收上傳時逾時的情況下回傳。通常是暫時性的，會在一至兩分鐘內自行恢復。

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 453,
      "message": "YouTube upload timed out (Google ingest). This is typically transient; please retry in 1–2 minutes.",
      "retryAvailable": true,
      "platform": "youtube"
    }
  ]
}

動作： 於 1–2 分鐘後採用指數退避重試貼文。請根據回應主體中的 retryAvailable 欄位（而非 HTTP 狀態）判斷是否可重試。你也可以使用 retry post 端點以相同 payload 重新提交。 Code 454 — YouTube 上傳服務暫時無法使用 (HTTP 503) 當 YouTube 上傳端點回傳 5xx 狀態，或至 YouTube 的連線在 socket 層被重設或逾時（ECONNRESET、ETIMEDOUT、ESOCKETTIMEDOUT）時回傳。這些皆為暫時性狀況。

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 454,
      "message": "YouTube upload service temporarily unavailable. Please retry.",
      "retryAvailable": true,
      "platform": "youtube"
    }
  ]
}

動作： 以指數退避重試貼文。請根據回應主體中的 retryAvailable 欄位（而非 HTTP 狀態）判斷是否可重試。你也可以使用 retry post 端點以相同 payload 重新提交。

YouTube 縮圖錯誤 Code 307

當自訂 YouTube thumbNail 無法套用時，會回傳 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 帳號則為次要原因。

{
  "status": "success",
  "id": "<videoId>",
  "thumbnail": {
    "action": "post",
    "status": "error",
    "code": 307,
    "message": "Your YouTube channel must be verified to set a custom thumbnail. Verify your channel at https://www.youtube.com/verify (phone verification). If your channel is already verified, try unlinking and re-linking your YouTube account to restore permissions.",
    "details": "<upstream message>"
  },
  "warnings": [
    {
      "feature": "thumbnail",
      "code": 307,
      "message": "Your YouTube channel must be verified to set a custom thumbnail. Verify your channel at https://www.youtube.com/verify (phone verification). If your channel is already verified, try unlinking and re-linking your YouTube account to restore permissions.",
      "details": "<upstream message>"
    }
  ]
}

Ayrshare 也會在可行時於發布前驗證縮圖：檔案必須是 PNG 或 JPG/JPEG、2MB 以下，並且來自可存取的網址。縮圖問題永遠不會讓貼文失敗——影片一定會發布，失敗總是以非致命的 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)。

Reddit 發布錯誤

Code 442 — Reddit 遭到 subreddit 封鎖 (HTTP 400) 當帳號已被目標 subreddit 禁止發文時回傳。此錯誤不可重試——原樣重新提交貼文不會成功。訊息會包含受影響的 subreddit 名稱（例如 r/news）。

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 442,
      "message": "You've been banned from posting to r/news. This post will not succeed on retry — remove it from your target subreddits.",
      "platform": "reddit"
    }
  ]
}

動作： 從目標 subreddits 中移除被禁的 subreddit。原樣重試不會成功。 Code 443 — Reddit 標題含禁用字詞 (HTTP 400) 當 subreddit 因貼文標題含禁用字詞而拒絕貼文時回傳。請在重試前編輯標題——原樣重新提交不會成功。訊息會包含受影響的 subreddit 名稱（例如 r/news）。

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 443,
      "message": "r/news rejected this post because the title contains a disallowed word. Edit the title before retrying — retrying as-is will not succeed.",
      "platform": "reddit"
    }
  ]
}

動作： 編輯貼文標題以移除禁用字詞後再重試。

內容審核錯誤

Code 438 — 內容審核輸入被拒 (HTTP 400) 當 AI 服務商拒絕所提供的輸入時，由 POST /validate/moderation 回傳——例如不支援的檔案類型。這是請求輸入層面的問題，並非暫時性處理失敗。

{
  "status": "error",
  "errors": [
    {
      "action": "moderation",
      "status": "error",
      "code": 438,
      "message": "There was an issue with the AI processing."
    }
  ]
}

動作： 確認內容審核輸入有效且使用支援的檔案類型後再重新提交。

請對照 code 438 與 code 331。Code 331 涵蓋相同的內容審核情境，但代表服務商端的實際處理失敗（HTTP 500，訊息「There was an issue with the AI processing. Please try again.」）。Code 331 為可重試的暫時性伺服器端失敗，而 code 438 表示輸入本身被拒絕，必須先更正才能重試。

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 會拒絕分析請求。發布本身不受影響。

{
  "action": "authorization",
  "status": "error",
  "code": 475,
  "message": "Your LinkedIn profile is missing the analytics permissions. Please re-link your LinkedIn profile to enable analytics.",
  "resolution": {
    "relink": true,
    "platform": "linkedin"
  }
}

動作： 請帳號擁有者到 Social Accounts 重新連結其 LinkedIn 個人檔案，以授與新的分析 scope，然後重試分析請求。重新連結後請等待幾分鐘再看錯誤是否清除：Ayrshare 會短暫快取此錯誤，且 LinkedIn 也會快取 token 的權限，因此已重新連結的檔案可能仍會回傳 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 而非一般性錯誤。

{
  "status": "error",
  "errors": [
    {
      "action": "get",
      "status": "error",
      "code": 288,
      "message": "TikTok video is still processing; the action is deferred until the post is live.",
      "platform": "tiktok"
    }
  ]
}

動作： 等 TikTok 處理完成後再重試。請監聽 tikTokPublished Scheduled Action webhook，或輪詢 /history 直到貼文 id 是解析後的數字 video id。第一則留言在貼文解析後會自動發布，因此無需重試。若貼文為 "failed"，訊息則會標示影片發布失敗且該動作不會執行。

錯誤訊息翻譯

API 錯誤訊息回應可以自動翻譯成你選擇的語言。若你想直接以使用者偏好的語言顯示錯誤，這將非常實用。若你想選擇社群連結頁面的語言，請參閱該連結。於標頭中加入：

"Translate-Error-Message": "Language_Code"

其中 Language_Code 為可用的語言代碼之一。例如，下列會將錯誤翻譯為法文。

"Translate-Error-Message": "fr" // Translate to French

我們的系統會自動偵測錯誤訊息的語言。

​處理錯誤

​Instagram 專屬錯誤碼

​可重試 (Retry Available)

​X/Twitter BYO Key 錯誤

​內文優化錯誤

​媒體抓取／爬蟲存取錯誤

​Facebook Analytics 速率限制

​Meta 身份驗證

​Facebook 帳號限制

​圖片格式轉換錯誤

​YouTube 暫時性上傳錯誤

​YouTube 縮圖錯誤 Code 307

​Reddit 發布錯誤

​內容審核錯誤

​LinkedIn Analytics 錯誤

​TikTok 留言錯誤

​錯誤訊息翻譯

處理錯誤

Instagram 專屬錯誤碼

可重試 (Retry Available)

X/Twitter BYO Key 錯誤

內文優化錯誤

媒體抓取／爬蟲存取錯誤

Facebook Analytics 速率限制

Meta 身份驗證

Facebook 帳號限制

圖片格式轉換錯誤

YouTube 暫時性上傳錯誤

YouTube 縮圖錯誤 Code 307

Reddit 發布錯誤

內容審核錯誤

LinkedIn Analytics 錯誤

TikTok 留言錯誤

錯誤訊息翻譯