> ## 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>
  错误响应的返回状态码可能为 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>
    如果 API 调用失败，顶层 `status` 字段会是 "error"。例如，对于 /post
    调用，如果所有社交网络发布都成功，`status` 字段会是 "success"；否则，
    `status` 字段会是 "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 的访问权限——发帖时会得到下面这样的响应，HTTP 返回码为 `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"
}
```

对应的处理可能是通过你的控制台、短信或邮件通知你的用户。

另一个例子是，如果发布到 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 发布失败的更具体信息，尽可能替代通用的 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 的 publish 接口直接返回 HTTP 429，或底层错误子码（`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` header 时，其值（以秒为单位）会通过 `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 策略——参见 [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）、Story（`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` 视频 URL，且不设置 `stories: true`。去掉多余的 `mediaUrls` 条目，或者如果你原本想发的是普通轮播 / Story 帖子，请移除 `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 账号，授予所有请求的权限，然后重新发布。对于其他账号状态错误，请先在 Meta 侧确认 Instagram 账号状态正常后再重试。

#### 可重试（Retry Available）

有时社交网络会遇到无法自动恢复的错误（例如它们的服务器出问题），即便经过多次重试，调用最终仍然失败。
在这些情况下，我们的系统会判断该错误是否可重试，如可重试，`retryAvailable` 字段将为 `true`。

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

之后你可以使用相同的请求体重试该调用。
如果是发帖，可以使用 [retry post](/apis/post/retry-post) 接口。

### X/Twitter BYO Key 错误

以下错误码专用于 X/Twitter BYO（自带）Key 操作：

**Code 272 - 无法验证 BYO Twitter 身份（HTTP 400）**

Ayrshare 无法通过你的 BYO consumer keys 以及关联时保存的 OAuth token 确认你的 X/Twitter 身份。响应结构会根据触发它的调用有所不同；两种形式都对应下面同样的三种子情况。请使用拥有 BYO 开发者应用的账号登录 [x.com](https://x.com) 来判断具体是哪一种。

发帖路径返回的是最小化响应：

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

分析路径返回的是更详尽、更具自描述性的消息，可能还包含一个 `details` 字段，携带 X 的原始错误字符串：

```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 会看到解锁验证（验证码、手机验证等）。**处理方式：** 在 x.com 上完成解锁验证，然后重试请求。无需重新关联。

**身份或密钥不匹配。** 你的 X 账号在 x.com 上状态正常，但你的 BYO consumer keys 对应的 X 开发者应用与关联时保存的 OAuth token 所属的应用不一致。**处理方式：** 在 Social Accounts 中重新关联 X，并使用拥有该 BYO 开发者应用的同一个 X 账号进行授权。

**Code 416 — X 额度耗尽（HTTP 402）**

你的 X 开发者账号没有加载任何 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 应用权限（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 中，将你的应用权限更新为 **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 凭证。当两个 header 都缺失或只提供了其中一个时，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`。如果只提供其中一个而缺少另一个，请求会以相同错误码被拒绝。完整 header 列表参见 [X BYO Keys Header 对照表](/dashboard/connect-social-accounts/x-twitter-byo-keys#header-reference)。

**Code 423 — 旧版 X/Twitter OAuth 不再支持（HTTP 403）**

当 X/Twitter 请求仍依赖旧的（非 BYO）OAuth 路径时返回，该路径已不再受支持。X API 访问现在需要通过请求头提供你自己的 X 开发者应用凭证。

```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 开发者应用，并在每一个指向 X 的请求中携带 `X-Twitter-OAuth1-Api-Key` 和 `X-Twitter-OAuth1-Api-Secret` header。完整步骤参见 [X BYO Key 配置指南](/dashboard/connect-social-accounts/x-twitter-byo-keys)。

### 文案增强错误

**Code 441 — 文案增强失败（HTTP 502）**

在为发帖准备内容时，某个或某些平台的文案增强（例如 [`shortenLinks`](/apis/post/post)）失败时返回。每一个受影响的平台都会出现在 `errors` 数组中，携带 `source: "handlePostAdditions"` 与 `code: 441`。

当只有部分平台失败时，其他平台仍会成功发布，其结果会出现在 `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 错误 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` 发布时，也出现与 code 440 / 138 相同的媒体抓取问题。Threads API 不会返回详情字符串，因此诊断通常需要在同一次发布中查看是否有并发的 Instagram 440 或 138 错误。

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

**处理方式：** 完整的排查方式（包括 `robots.txt` 片段与一个验证命令）请参见 [Meta 媒体爬虫被阻止](/help-center/technical-support/meta_media_crawler_blocked)。

### Facebook 分析速率限制

**Code 444 — Facebook Page 分析速率限制（HTTP 429）**

当某个 Facebook Page 超过 Meta 对该 Page 分析接口的速率限制时返回。底层的 Meta 错误是 `80001`（"There have been too many calls to this Page account."）。该 Page 仍保持关联，发布仍可正常进行——仅仅是该 Page 的分析扇出被限流。

在 [`/history/facebook`](/apis/history/history-platform) 或 [analytics](/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 的按 Page 速率限制窗口通常会在一小时内自行恢复，不需要对该 Page 做任何操作。**请勿**提示用户重新关联账号——这是 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 错误子码 `2424009` 和 `1404078`，或错误没有子码但携带 Meta 的限制措辞时）。这是账号级别的限制，而不是瞬时的发布问题——它**不可重试**，也**不会**携带 `retryAvailable` 标记。除非在 Meta 侧解决该限制，否则重新提交同一条帖子不会成功。账号仍与 Ayrshare 保持关联，不需要重新关联。

Meta 不通过 API 返回具体的限制原因，因此客户必须直接在 Meta 的 Account Status 页面查看原因并进行申诉。当 Meta 提供了原样文本时，Ayrshare 会将其放在 `details` 字段中。此外，Ayrshare 在检测到限制时会向账号所有者发送一封通知邮件。

```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（WebP 转换适用于 Instagram、LinkedIn、TikTok、Google My Business、Threads 和 Snapchat；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、网络超时、重定向链超过跳数上限，或 URL 解析到了非公开地址（被 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 解析）。如果 URL 存在重定向，请确保最终目的地也是公开的且不在私有网络内。

**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 ingest 流水线在接收上传时超时时返回。这通常是瞬时性的，会在一两分钟内自行恢复。

```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) 接口重新提交相同的请求体。

**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) 接口重新提交相同的请求体。

### YouTube 缩略图错误 Code 307

当自定义 YouTube `thumbNail` 无法应用时会返回 `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**、并通过**可访问的 URL** 提供。

缩略图问题**永远不会导致帖子失败**——视频总是会发布，失败会作为非致命的 `warnings` 条目出现（顶层 `status` 仍为 `"success"`）。无论问题何时被检测到都是如此：

* **上传前捕获。** 当预发布校验能明确判断缩略图不合规时（文件类型错误、确认超过 2MB，或 URL 不可访问），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 缩略图未应用（未验证频道）](/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"
    }
  ]
}
```

**处理方式：** 从目标 subreddit 列表中移除该被封禁的 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 分析错误

**Code 475 — 需要重新关联 LinkedIn 资料以启用分析（HTTP 403）**

对于在成员分析上线之前就已经关联的个人（成员）LinkedIn 资料，[`POST /analytics/post`](/apis/analytics/post) 与 [`POST /analytics/social`](/apis/analytics/social) 会返回该错误。这些资料缺少 LinkedIn 成员分析所需的作用域（`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 资料以授予新的分析作用域，然后重试分析请求。重新关联后，请预留几分钟让该错误消退：Ayrshare 会短暂缓存此错误，同时 LinkedIn 也会缓存 token 的权限，因此重新关联的资料在分析恢复之前可能仍会返回约 5–10 分钟的 `475`。

### TikTok 评论错误

**Code 288 — TikTok 评论被延后 / 帖子仍在处理中（HTTP 400）**

TikTok 异步处理视频，因此在 TikTok 的 `post.publish.publicly_available` webhook 解析出真实的视频 ID 之前，新发布帖子的 `id` 会是 `"pending"`。对仍在处理中的帖子（或 `id` 为 `"failed"` 的帖子）发起的[获取评论](/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` 变为解析后的数字视频 ID。[首条评论](/apis/post/overview#first-comment) 在帖子完成后会自动发布，因此无需重试。对于 `"failed"` 的帖子，消息会改为指出视频未能发布，且相关操作不会执行。

### 错误消息翻译

API 错误消息响应可以自动翻译为你选择的语言。
如果你想直接以用户偏好的语言向他们展示错误，这非常有用。

如果你想[选择社交关联页面的语言](/multiple-users/manage-user-profiles#set-language-for-the-social-linking-page)，请参见此处。

在 header 中加入：

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

其中 `Language_Code` 是可用的[语言代码](/iso-codes/language)之一。

例如，以下代码会将错误翻译为法语。

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

我们的系统会自动检测错误消息的语言。