Ayrshare 错误码 - Ayrshare API Documentation

在适用时，REST API 会在响应中包含一个错误列表。

错误响应的返回状态码可能为 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 指的是所返回错误的类型。
如果 API 调用失败，顶层 status 字段会是 “error”。例如，对于 /post 调用，如果所有社交网络发布都成功，status 字段会是 “success”；否则， status 字段会是 “error”。
code 字段包含 Ayrshare 的参考错误码。
message 字段是该错误的具体细节。

错误处理

你应对任何错误响应进行处理并采取相应操作。发生错误的情况包括：

响应返回码不是 200
JSON 响应的 status 为 error

例如，如果你的用户移除了 Facebook 关联——他们修改了密码，或撤销了 Ayrshare 的访问权限——发帖时会得到下面这样的响应，HTTP 返回码为 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"
}

对应的处理可能是通过你的控制台、短信或邮件通知你的用户。另一个例子是，如果发布到 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 发布失败的更具体信息，尽可能替代通用的 138 错误。 Code 435 — Instagram 速率限制（HTTP 429） Instagram 专业账号（Business / Creator）受 Meta Content Publishing API 的滚动 24 小时 50 条发帖上限约束（个人账号完全无法通过 API 发布，因此不会触发该限制）。超出上限后，Meta 会返回速率限制错误。当 Meta 的 publish 接口直接返回 HTTP 429，或底层错误子码（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 header 时，其值（以秒为单位）会通过 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 策略——参见 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）、Story（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 视频 URL，且不设置 stories: true。去掉多余的 mediaUrls 条目，或者如果你原本想发的是普通轮播 / Story 帖子，请移除 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 账号，授予所有请求的权限，然后重新发布。对于其他账号状态错误，请先在 Meta 侧确认 Instagram 账号状态正常后再重试。

可重试（Retry Available）

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

{
  "retryAvailable": true
}

之后你可以使用相同的请求体重试该调用。如果是发帖，可以使用 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 来判断具体是哪一种。发帖路径返回的是最小化响应：

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

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

{
  "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 调用都需要额度。

{
  "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 应用权限（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 中，将你的应用权限更新为 Read and write and Direct message，然后在 Keys and tokens 中重新生成 Access Token。新的 token 将继承更新后的权限。详情参见 X BYO Key 配置指南。 Code 419 - 缺少 BYO 凭证（HTTP 400） X/Twitter 操作要求在请求头中提供 BYO API 凭证。当两个 header 都缺失或只提供了其中一个时，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。如果只提供其中一个而缺少另一个，请求会以相同错误码被拒绝。完整 header 列表参见 X BYO Keys Header 对照表。 Code 423 — 旧版 X/Twitter OAuth 不再支持（HTTP 403） 当 X/Twitter 请求仍依赖旧的（非 BYO）OAuth 路径时返回，该路径已不再受支持。X API 访问现在需要通过请求头提供你自己的 X 开发者应用凭证。

{
  "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 配置指南。

文案增强错误

Code 441 — 文案增强失败（HTTP 502） 在为发帖准备内容时，某个或某些平台的文案增强（例如 shortenLinks）失败时返回。每一个受影响的平台都会出现在 errors 数组中，携带 source: "handlePostAdditions" 与 code: 441。当只有部分平台失败时，其他平台仍会成功发布，其结果会出现在 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 错误 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 发布时，也出现与 code 440 / 138 相同的媒体抓取问题。Threads API 不会返回详情字符串，因此诊断通常需要在同一次发布中查看是否有并发的 Instagram 440 或 138 错误。

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

处理方式： 完整的排查方式（包括 robots.txt 片段与一个验证命令）请参见 Meta 媒体爬虫被阻止。

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 或 analytics 响应中，如果检测到某条帖子被限流，则该帖子会在 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 的按 Page 速率限制窗口通常会在一小时内自行恢复，不需要对该 Page 做任何操作。请勿提示用户重新关联账号——这是 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 错误子码 2424009 和 1404078，或错误没有子码但携带 Meta 的限制措辞时）。这是账号级别的限制，而不是瞬时的发布问题——它不可重试，也不会携带 retryAvailable 标记。除非在 Meta 侧解决该限制，否则重新提交同一条帖子不会成功。账号仍与 Ayrshare 保持关联，不需要重新关联。 Meta 不通过 API 返回具体的限制原因，因此客户必须直接在 Meta 的 Account Status 页面查看原因并进行申诉。当 Meta 提供了原样文本时，Ayrshare 会将其放在 details 字段中。此外，Ayrshare 在检测到限制时会向账号所有者发送一封通知邮件。

{
  "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。最常见的原因是源文件损坏、容器内的内部格式异常，或图片超出了转换的大小上限。

{
  "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 字段（若存在）会携带底层的原因字符串。

{
  "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 侧的内部故障，可重试。

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

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

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 账号。

{
  "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 验证你的 YouTube 频道（手机验证）。如果你的频道已经验证过而缩略图仍然失败，请在 Social Accounts 页面解除并重新关联 YouTube 账号，同时授予所有权限。完整排查指南参见 YouTube 缩略图未应用（未验证频道）。

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"
    }
  ]
}

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

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

TikTok 评论错误

Code 288 — TikTok 评论被延后 / 帖子仍在处理中（HTTP 400） TikTok 异步处理视频，因此在 TikTok 的 post.publish.publicly_available webhook 解析出真实的视频 ID 之前，新发布帖子的 id 会是 "pending"。对仍在处理中的帖子（或 id 为 "failed" 的帖子）发起的获取评论、评论或回复请求会在调用 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 变为解析后的数字视频 ID。首条评论在帖子完成后会自动发布，因此无需重试。对于 "failed" 的帖子，消息会改为指出视频未能发布，且相关操作不会执行。

错误消息翻译

API 错误消息响应可以自动翻译为你选择的语言。如果你想直接以用户偏好的语言向他们展示错误，这非常有用。如果你想选择社交关联页面的语言，请参见此处。在 header 中加入：

"Translate-Error-Message": "Language_Code"

其中 Language_Code 是可用的语言代码之一。例如，以下代码会将错误翻译为法语。

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

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

​错误处理

​Instagram 专属错误码

​可重试（Retry Available）

​X/Twitter BYO Key 错误

​文案增强错误

​媒体抓取 / 爬虫访问错误

​Facebook 分析速率限制

​Meta 身份验证

​Facebook 账号限制

​图片格式转换错误

​YouTube 瞬时上传错误

​YouTube 缩略图错误 Code 307

​Reddit 发布错误

​内容审核错误

​LinkedIn 分析错误

​TikTok 评论错误

​错误消息翻译

错误处理

Instagram 专属错误码

可重试（Retry Available）

X/Twitter BYO Key 错误

文案增强错误

媒体抓取 / 爬虫访问错误

Facebook 分析速率限制

Meta 身份验证

Facebook 账号限制

图片格式转换错误

YouTube 瞬时上传错误

YouTube 缩略图错误 Code 307

Reddit 发布错误

内容审核错误

LinkedIn 分析错误

TikTok 评论错误

错误消息翻译