> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ayrshare 錯誤碼

> Ayrshare 專屬的回傳錯誤碼。

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

<Info>
  錯誤的 HTTP 狀態碼為 400、401、402、403、404、429、500、502、503 或 504；成功時狀態碼為 200。詳情請見[此處](/errors/errors-http)。
</Info>

每個 API 呼叫可能因為請求本身或社群網路端遇到的問題而回傳不同的錯誤。
錯誤回應會包含此次 API 呼叫失敗的詳細資訊。

例如，被 Twitter 與 Facebook 判定為重複的貼文會回傳下列回應：

```json theme={"system"}
{
  "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"
}
```

請注意：

<ul class="custom-bullets">
  <li>
    `errors` 欄位包含錯誤陣列，每個發生錯誤的社群網路各對應一筆。
  </li>

  <li>`action` 代表所回傳錯誤的類型。</li>

  <li>
    最上層的 `status` 欄位在 API 呼叫失敗時為「error」。例如，對於 /post 呼叫，若所有社群網路的貼文皆成功，`status` 欄位會是「success」；否則為「error」。
  </li>

  <li>`code` 欄位為 Ayrshare 的參考錯誤碼。</li>
  <li>`message` 欄位為錯誤的具體細節。</li>
</ul>

### 處理錯誤

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

<ul class="custom-bullets">
  <li>回應的狀態碼不是 `200`</li>
  <li>JSON 回應的 status 為 `error`</li>
</ul>

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

```json theme={"system"}
{
  "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`：

```json theme={"system"}
{
  "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](https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user/content_publishing_limit/) 上有 24 小時內滾動 50 篇貼文的限制（個人帳號完全無法透過 API 發布，因此永遠不會觸發此限制）。當達到上限時，Meta 會回傳速率限制錯誤。當 Meta 的發布端點直接回傳 HTTP 429，或底層的 error subcode（`1390008`）指出貼文／留言遭到節流時，Ayrshare 也會以 `code: 435` 呈現。

```json theme={"system"}
{
  "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 伺服器高負載時期。

```json theme={"system"}
{
  "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](/apis/post/retry-post) 端點重試貼文。若問題持續發生，請嘗試縮小媒體檔案。

**Code 447 — Instagram Trial Reels：缺少 graduationStrategy (HTTP 400)**

當 [`/post`](/apis/post/post) 請求提供了 `instagramOptions.trialParams`，但 `graduationStrategy` 為缺失、`null` 或空字串時回傳。Trial reels 需要明確的 graduation strategy——請參閱 [Trial Reels](/apis/post/social-networks/instagram#trial-reels)。

```json theme={"system"}
{
  "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 個字元）以便偵錯。

```json theme={"system"}
{
  "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` 欄位會指出實際觸發的子情況。

```json theme={"system"}
{
  "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 帳號狀態（而非貼文內容）拒絕請求時出現。

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

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

```json theme={"system"}
{
  "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](https://app.ayrshare.com/social-accounts) 中取消連結並重新連結 Instagram 帳號，授與所有要求的權限，然後重試貼文。對於其他帳號狀態錯誤，請確認 Instagram 帳號在 Meta 上處於良好狀態後再重試。

#### 可重試 (Retry Available)

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

```json theme={"system"}
{
  "retryAvailable": true
}
```

你可以用相同的 payload 重試呼叫。
若為貼文，可使用 [retry post](/apis/post/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](https://x.com) 以確認實際情況。

貼文路徑會回傳精簡的回應：

```json theme={"system"}
{
  "status": "error",
  "code": 272,
  "message": "Failed to verify BYO Twitter identity",
  "platform": "twitter"
}
```

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

```json theme={"system"}
{
  "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 呼叫都需要點數。

```json theme={"system"}
{
  "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](https://console.x.com) → Billing → Credits 購買點數。即使只有 \$5 也足以進行數百次 API 呼叫。

**Code 417 — OAuth 1.0a App 權限 (HTTP 403)**

你的 X Access Token 沒有執行所請求操作的正確權限。

```json theme={"system"}
{
  "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 設定指南](/dashboard/connect-social-accounts/x-twitter-byo-keys#troubleshooting)。

**Code 419 - 缺少 BYO 憑證 (HTTP 400)**

X/Twitter 操作需在請求標頭中提供 BYO API 憑證。當兩個標頭皆缺失，或成對中僅提供其中之一時，Ayrshare 皆會回傳 code 419。`message` 字串會因缺少的標頭而不同。

當 `X-Twitter-OAuth1-Api-Key` 與 `X-Twitter-OAuth1-Api-Secret` 皆缺失時：

```json theme={"system"}
{
  "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）：

```json theme={"system"}
{
  "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](/dashboard/connect-social-accounts/x-twitter-byo-keys#header-reference)。

**Code 423 — 舊版 X/Twitter OAuth 已不再支援 (HTTP 403)**

當 X/Twitter 請求仍依賴舊版（非 BYO）OAuth 流程時回傳，該流程已不再支援。X API 存取現在需要透過請求標頭提供你自己的 X Developer App 憑證。

```json theme={"system"}
{
  "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 設定指南](/dashboard/connect-social-accounts/x-twitter-byo-keys)。

### 內文優化錯誤

**Code 441 — 內文優化失敗 (HTTP 502)**

當在準備貼文時，某個或多個平台的內文優化（例如 [`shortenLinks`](/apis/post/post)）失敗時回傳。每個受影響的平台會以 `source: "handlePostAdditions"` 與 `code: 441` 出現在 `errors` 陣列中。

當只有部分平台失敗時，其他平台仍會成功發布，其結果會出現在 `postIds` 中。此時最上層的 `status` 為 `"error"`，但 `postIds` 不為空——客戶端應將 `status` 與 `errors[]` 視為互補而非互斥。

```json theme={"system"}
{
  "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`，且不會建立任何貼文：

```json theme={"system"}
{
  "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 文字。

```json theme={"system"}
{
  "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` 字串辨識。

```json theme={"system"}
{
  "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 來診斷。

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

**動作：** 完整的疑難排解請見 [Meta 媒體爬蟲被封鎖](/help-center/technical-support/meta_media_crawler_blocked)，包含 `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`](/apis/history/history-platform) 或[分析](/apis/analytics/social)回應中偵測到單一貼文的節流時，每個受影響的貼文會在 `facebook.code` 帶有 `code: 444` 與 `errCode: 80001`：

```json theme={"system"}
{
  "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 端的暫時性節流，並非授權失敗。

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

### Meta 身份驗證

**Code 326 — 需要 Meta 身份驗證 (HTTP 403)**

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

```json theme={"system"}
{
  "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](https://www.facebook.com/business-support-home) 完成 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 給帳號擁有者。

```json theme={"system"}
{
  "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。最常見原因是原始檔案損毀、容器內部含有非預期的格式，或圖片超過轉換的大小上限。

```json theme={"system"}
{
  "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` 欄位若存在，會帶有底層原因字串。

```json theme={"system"}
{
  "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 端的內部失敗，可以重試。

```json theme={"system"}
{
  "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 匯入流程在接收上傳時逾時的情況下回傳。通常是暫時性的，會在一至兩分鐘內自行恢復。

```json theme={"system"}
{
  "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](/apis/post/retry-post) 端點以相同 payload 重新提交。

**Code 454 — YouTube 上傳服務暫時無法使用 (HTTP 503)**

當 YouTube 上傳端點回傳 5xx 狀態，或至 YouTube 的連線在 socket 層被重設或逾時（`ECONNRESET`、`ETIMEDOUT`、`ESOCKETTIMEDOUT`）時回傳。這些皆為暫時性狀況。

```json theme={"system"}
{
  "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](/apis/post/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 帳號則為次要原因。

```json theme={"system"}
{
  "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](https://www.youtube.com/verify) 驗證你的 YouTube 頻道（電話驗證）。若頻道已驗證但縮圖仍失敗，請到 [Social Accounts](https://app.ayrshare.com/social-accounts) 取消連結並重新連結 YouTube 帳號並授與所有權限。完整疑難排解請見 [YouTube Thumbnail Not Applied (Unverified Channel)](/help-center/technical-support/youtube_thumbnail_unverified_channel)。

### Reddit 發布錯誤

**Code 442 — Reddit 遭到 subreddit 封鎖 (HTTP 400)**

當帳號已被目標 subreddit 禁止發文時回傳。此錯誤**不可**重試——原樣重新提交貼文不會成功。訊息會包含受影響的 subreddit 名稱（例如 `r/news`）。

```json theme={"system"}
{
  "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`）。

```json theme={"system"}
{
  "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`](/apis/post/post) 回傳——例如不支援的檔案類型。這是請求輸入層面的問題，並非暫時性處理失敗。

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

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

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

### LinkedIn Analytics 錯誤

**Code 475 — 重新連結 LinkedIn 個人檔案以取得分析 (HTTP 403)**

當個人（member）LinkedIn 檔案是在 member analytics 上線之前完成連結時，由 [`POST /analytics/post`](/apis/analytics/post) 與 [`POST /analytics/social`](/apis/analytics/social) 回傳。這些檔案缺少 LinkedIn member analytics 的 scope（`r_member_postAnalytics`、`r_member_profileAnalytics`），因此 LinkedIn 會拒絕分析請求。發布本身不受影響。

```json theme={"system"}
{
  "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](https://app.ayrshare.com/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](/apis/comments/get-comments)、留言或回覆請求時，會在呼叫 TikTok 之前被拒絕，並回傳 code 288 而非一般性錯誤。

```json theme={"system"}
{
  "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](/apis/webhooks/actions#scheduled-action)，或輪詢 [/history](/apis/history/overview) 直到貼文 `id` 是解析後的數字 video id。[第一則留言](/apis/post/overview#first-comment)在貼文解析後會自動發布，因此無需重試。若貼文為 `"failed"`，訊息則會標示影片發布失敗且該動作不會執行。

### 錯誤訊息翻譯

API 錯誤訊息回應可以自動翻譯成你選擇的語言。
若你想直接以使用者偏好的語言顯示錯誤，這將非常實用。

若你想[選擇社群連結頁面的語言](/multiple-users/manage-user-profiles#set-language-for-the-social-linking-page)，請參閱該連結。

於標頭中加入：

```json theme={"system"}
"Translate-Error-Message": "Language_Code"
```

其中 `Language_Code` 為可用的[語言代碼](/iso-codes/language)之一。

例如，下列會將錯誤翻譯為法文。

```json theme={"system"}
"Translate-Error-Message": "fr" // Translate to French
```

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