Ayrshare 错误码

在适用时，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?"
}

对应的处理可能是以正确的比例重新提交图片。

每月发帖配额

Code 106 — 超出每月发帖配额（HTTP 429） 该资料已用完其每月发帖配额。/post 会对新的发帖请求返回此错误，包括将帖子排期的请求。其他帖子相关请求（例如获取、删除或重试帖子，或帖子分析）在配额重置前也会返回此错误。在配额用完期间到期的已排期帖子也会以此代码失败。这不是速率限制，等待几分钟也无济于事。通常，整个响应就是该错误：

{
  "action": "quota limit",
  "status": "error",
  "code": 106,
  "message": "You have exceeded your API quota for the month. Please see our upgrade plans. https://www.ayrshare.com/pricing/"
}

对于已排期的帖子，同样的错误会出现在该帖子的 errors 数组中。如果在发送新帖子的过程中配额用完，新帖子也可能出现这种情况。请在这两处都检查 code: 106。 处理方式： 通过 User Profile 详情查看 monthlyPostCount 和 monthlyPostQuota。配额在每月 1 日（UTC）重置。更改计划会立即重置你的 Primary Profile 的计数。失败的发帖尝试也会计入，因此请停止对持续失败的帖子进行自动重试。详情请参见我可以发布多少帖子和调用多少 API？。

重复与相似内容错误

在帖子发送到社交网络之前，Ayrshare 会将其与你的其他帖子进行比对，并以代码 137 拒绝完全相同或高度相似的内容。这是 Ayrshare 自己的检查，因此即使社交网络本身会放行，帖子也可能被拒绝。该检查并不覆盖所有平台——请参阅下文的例外情况。

代码	HTTP	含义
137	400	在该帖子的重复检查窗口内，已存在完全相同或高度相似的已排期或已发布内容。参见处理重复帖子。

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 137,
      "message": "Duplicate or similar content posted within the same two day period. The social networks prohibit duplicate content and ban accounts that do not comply. https://www.ayrshare.com/docs/help-center/technical-support/dealing_with_duplicate_posts#dealing-with-duplicate-posts",
      "platform": "twitter"
    }
  ],
  "postIds": [],
  "id": "Jxe2nMM3FmEvMXFSY3g4"
}

检查窗口。 每个帖子都会在以其自身 scheduleDate 为中心的 48 小时窗口内进行检查——前 24 小时到后 24 小时。由于该窗口既向后也向前查看，帖子可能因为排在它之后的帖子而被拒绝，而不仅仅是排在它之前的帖子。 比对范围。

匹配按用户配置文件（User Profile）和按平台分别进行。同一段文本分别发送到 X/Twitter 和 LinkedIn 不算重复，两个不同的用户配置文件之间也不会冲突。
X/Twitter 是例外，但仅适用于完全相同的重复内容：完全相同的帖子还会核对同一账户下的所有用户配置文件，因为 X 不允许在多个账号之间发布相同内容。高度相似（而非完全相同）的内容检查仍只限于发帖所用的单个用户配置文件。
Pinterest、Reddit 和 Telegram 不做重复检查。

如需更频繁地发布同一主题的内容，可使用 Generate API 创建不同的版本。

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（“Generic Internal Error”，通用内部错误）时，这是 Meta 侧的临时故障。Ayrshare 会自动重试发布，最长约 50 秒，然后才返回该错误，响应中会设置 retryAvailable: true，但不会设置 relink: true —— 重新关联账号无法解决这种情况。当 Meta 返回 fbtrace_id 时，该值会包含在 details 中：

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 258,
      "message": "Instagram reported a temporary internal error while publishing (Meta error 2207085 - Generic Internal Error). This is a Meta-side condition and usually resolves on its own - please retry the post in a few minutes. If the error persists beyond 24-48 hours, unlink and relink your Instagram account on the Social Accounts page, granting all permissions on the Meta authorization screen, or contact Meta support with the trace ID provided in the details field of this error response.",
      "retryAvailable": true,
      "details": "Meta fbtrace_id: AMzDbKKh3d7n-oufgbiTut5",
      "platform": "instagram"
    }
  ]
}

处理方式： 对于 2207085 子情况，请在几分钟后重试发布 —— 这是 Meta 侧的状况，通常会自行恢复，重新关联账号并不能解决。仅当错误持续超过 24-48 小时时，才提示用户在 Social Accounts 页面解除并重新关联其 Instagram 账号，授予所有请求的权限，或携带 details 中的 fbtrace_id 联系 Meta 支持。对于其他账号状态错误，请先在 Meta 侧确认 Instagram 账号状态正常后再重试。

可重试（Retry Available）

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

{
  "retryAvailable": true
}

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

Instagram Reels 音频错误

这些错误码涉及使用 instagramOptions.audioConfiguration 为 Instagram Reel 附加音乐，以及音频搜索和音频查询端点。

代码	HTTP	含义
514	400	Instagram 通过 Instagram Login 连接。Meta 的 Audio API 需要 Facebook Login，因此搜索、查询和音乐附加都会被拒绝。请通过 Facebook Login 重新关联。
515	400	在非 Reel 的媒体上发送了 `audioConfiguration`。Stories、图片和轮播无法携带附加曲目。
516	400	`audioConfiguration` 缺少可用的 `audioId`。请从音频搜索或音频查询端点获取。
517	400	Instagram 拒绝了该曲目。该 id 可能无效、在你的地区受限，或未获得此用途的授权。
518	200	警告，而非错误。 `audioName` 因同时发送了 `audioConfiguration` 而被忽略。帖子仍已发布。

代码 514 无法通过授予权限或升级计划来解决。 Meta 的 Audio API “仅在使用 Facebook Login 的 Instagram API 上可用。使用 Instagram Login 的 Instagram API 不支持该功能。” 使用 Instagram Login 关联的账号在每次音频调用上都会返回 514，直到通过 Facebook Login（并连接了 Facebook Page）重新关联为止。完整设置请参见音乐附加资格指南，其中包括 Facebook Page 连接目前在 Facebook 设置中所处的位置。

代码 518 出现在 postIds[].warnings[] 上，而不是 errors[]。 Instagram 每条 Reel 只允许一个曲目，因此当同时发送 audioConfiguration 和 audioName 时，audioConfiguration 生效，audioName 被丢弃。响应仍为 status: "success" 且 HTTP 为 200——请将 518 视为提示信息，不要因它而判定失败。该警告嵌套在对应平台的 postIds 条目上，而不是位于顶层，并携带 feature: "audioName"。

音量校验报告的是通用的 101，而非专用代码。 audioVolume 和 videoVolume 必须是 0 到 100 的整数。小数、数字字符串（例如 "80"）、超出范围的数字或显式的 null 都会在调用 Instagram 之前返回 code: 101，并在 details 中指明相应的限制。请省略该字段，而不要发送 null。

自动化私信回复（评论 DM）错误

这些错误码会出现在评论触发的自动化（comment_keyword）上，当携带私信的私信回复无法发送时。它们会以活动条目 status: "failed" 出现，原因位于 actionResults[].errorDetails。它们都不会被自动重试——Instagram 的 Send API 没有幂等键，自动重试可能导致该私信被投递两次。不同错误码的处理方式不同（见下方 处理方式）：大多数对于该特定评论是永久性的；492 需要重新关联账户；493 会随每小时限额重置而自行恢复。

代码	HTTP	含义
490	400	该评论已不存在——Instagram 报告该评论 ID 本身无效。
491	400	Instagram 拒绝接受对该评论的私信回复。同一个代码，多种原因——请见下方说明。
492	403	该账户缺少 `instagram_business_manage_comments` 权限。请重新关联账户以授予该权限。
493	429	已达到 Instagram 的每小时私信回复限额（每账户 750 条/小时）。等待下一小时到来后自动恢复。
494	500	由于源评论 ID 不可用（内部配置错误；不会尝试回退），该自动化无法运行。
495	400	Instagram 因尚未映射到具体代码的原因拒绝该私信回复。Instagram 自身的说明位于 `errorDetails`。

代码 491 涵盖 Instagram 不加区分的多种原因，而 490 是狭窄的例外。 Instagram 对以下情况返回同一个共用错误：评论超过 7 天、评论已经收到过回复（每条评论只允许一条私信回复）、评论已被删除、评论者屏蔽了消息请求。以上所有情况都会报告 491。490 仅在 Instagram 直接将评论 ID 判定为无效，而不是返回上述共用类别时才会出现——因此一条被删除的评论可能报告为 490 或 491，取决于 Instagram 返回的是哪一个。由于 API 并不区分这些情形，请始终读取 errorDetails：其中携带 Instagram 自身的原文，通常对原因说明得较为具体。

代码 489 已被保留，目前不会返回。 它被留给”该评论已存在回复”的情形，Instagram 目前不将其作为一个独立信号公开——今天该情形报告为 491。之所以列在此处，是为了避免该编号被复用。

真正过期或失效的连接不在此范围内。 如果所存储的 Instagram 凭据已过期，活动条目会为 status: "auth_error" 而不是 failed，正确的解决方式是重新关联账户。除 492（缺少权限，需重新关联账户以授予）之外，上述代码都是评论层面的条件，绝不表示”需要重新关联”。

依据你从哪里读取，这些错误码会以两种不同的形态出现，而携带 Instagram 原因的字段在两种形态下的名称也不同。 1. 在自动化活动条目上 —— 即 GET /automations/:id/activity 返回的内容。Instagram 的原因位于 actionResults[].errorDetails：

{
  "status": "failed",
  "commentId": "18012345678905555",
  "actionResults": [
    {
      "type": "send_dm",
      "status": "failed",
      "errorDetails": "Cannot send private reply: This comment is no longer eligible for a private reply."
    }
  ]
}

2. 作为直接 API 错误封装 —— 标准的错误结构，其中同样的原因位于 details：

{
  "action": "messages",
  "status": "error",
  "code": 491,
  "message": "Instagram would not accept a private reply to this comment. The comment may be more than 7 days old, may already have a reply, may have been deleted, or the commenter may not allow message requests.",
  "details": "Cannot send private reply: This comment is no longer eligible for a private reply.",
  "platform": "instagram"
}

对于评论触发的自动化，你几乎总是在读取形态 1。那里的 errorDetails 与封装中 details 携带的是同一个字符串。 处理方式：

490、491、495 —— 属于每条评论级别的条件。对于该特定评论无法恢复，任何重试都无济于事；在下一条新评论上，自动化会正常运行。请阅读 errorDetails 查看 Instagram 给出的原因。
492 —— 重新关联 Instagram 账户，并授予所有请求的权限。这是账户级别的修复，否则会影响每一条评论。
493 —— 除等待外无需任何操作；每小时限额会自行重置。不会自动重试，因此该评论对应的私信不会被发送。
494 —— 内部配置错误，不属于客户侧问题。如果反复出现，请联系支持。

sent 状态并不保证已投递。 除了上述失败之外，Instagram 接受的私信回复（status: "sent"）仍然可能在收件人的 Instagram Message requests 设置屏蔽陌生人时被静默丢弃——这种情况根本不会产生错误码。请参见自动化私信已发送但未送达。

线程与媒体选项错误

当某个选项无法应用于帖子时会返回这些错误码——最常见于 X 线程或 Threads 线程，因为你发送的选项会应用于整个线程。

182 —— 视频不满足时长要求。 视频短于该社交网络的最小时长或长于其最大时长。响应中会给出视频的实际时长以及所应用的最小值和最大值，请对比三者以确认触及的是哪一个界限。在 X 上，标准范围为 0.5 到 140 秒（2 分 20 秒）；若要发布更长的视频，请设置 longVideo: true，对于已获 X 批准发布长视频的账户，这会将上限提升到 4 小时。其他社交网络有各自的限制——请参见你要发布到的社交网络的媒体指南。
101 —— 参数缺失或不正确。 在 Threads 上，当从 Meta 未授予地理限制资格的账户发送 allowCountries 时会返回此错误。帖子或线程的任何部分都不会发布。请在发送该选项之前检查 /user 上的 isEligibleForGeoRestrictions。
111 —— X 拒绝了该帖子。 这是没有更具体代码的 X 失败的通用错误码，因此请阅读响应中的 details——它携带 X 自身的消息，能告诉你失败的原因。一个常见原因是账户无权使用某个选项，例如在没有 X Subscriptions 的情况下使用 subscribersOnly，或在没有 X Premium 的情况下在单条帖子上使用 longPost；这种情况下请移除该选项或检查账户的权益。连接失败和其他 X 侧错误也会以 111 呈现，对这类错误值得重试，而不是修改你的请求。注意，在线程上 longPost 不会导致 111——在线程上它会被忽略并附带一条警告，线程照常发布。参见长帖子。
275 —— 帖子太长，无法作为线程发布。 拆分文本后产生的帖子数量超过了 30 条的上限。请缩短文本，或将其拆分到多个独立的线程中。用 \n\n 添加你自己的线程分隔符在这里无济于事——每个分隔符都会创建另一条帖子，因此可能使数量进一步超出限制。

你的账户无法使用的选项会导致整条帖子失败，而不是被忽略。对线程而言，这意味着线程的任何部分都不会发布——已经发出的部分会为你自动删除。删除是尽力而为的：如果社交网络拒绝删除操作，该部分可能仍保持已发布状态，因此请检查线程并移除任何遗留内容。此前这些选项中的一部分在线程上会被静默丢弃，线程在不带它们的情况下照常发布。

Link Session 错误

错误码 501 到 513 属于社交关联：使用创建 Link Session 创建链接，以及打开链接。它们携带 "action": "link session"。本页上其他 500 系列错误码与此无关 ——514 到 518 是 Instagram Reels 音频。

代码	HTTP	消息	处理方法
501	403	This social linking session has been revoked. Please request a new linking URL.	链接在你的用户打开之前已被吊销。请创建新的链接。
502	404	Social linking session not found. Please request a new linking URL.	链接不存在——通常是被截断或改动过的 URL，或已超过保留期限的链接。请创建新的链接。
503	401	This social linking session has expired. Please request a new linking URL.	链接默认有效 5 分钟。请在用户准备使用时再创建链接，或调高 `expiresIn`（最多 2880 分钟，需 Max Pack）。
504	401	Connect mode requires the Max Pack. Activate it on your Account page: https://app.ayrshare.com/account	`mode: "connect"` 需要 Max Pack。它在 connect 模式参数之前检查，因此修正 `origin` 或 `network` 不会改变这个结果。如果你需要在没有 Max Pack 的情况下启用，请联系支持团队。
505	400	Connect mode requires an origin. Provide the origin the embedded widget will run on.	发送 `origin`——你的页面运行所在的确切 origin。connect 模式下必需，grid 模式下可选。
506	400	The origin is not a supported shape. Provide an https origin, a custom scheme such as myapp://connected, or http://localhost:3000 for local development.	只发送 origin 本身，别无其他：不带路径、查询、片段或凭据。`details` 会复述你发送的值。
507	400	The network and allowedSocial parameters cannot be combined. A single-network session is already its own allowlist.	去掉其中之一。直连模式会话用 `network`，限定托管关联页面范围用 `allowedSocial`。
508	400	The network is not recognized. Check the supported network names in the documentation.	对照 `network` 参数检查拼写。`fbg` 不是关联目标，总会落在这里。
509	403	The network is not enabled for this account. Enable it in Profile Settings or contact support.	名称有效，但你的账户尚未启用它。请在社交网络页面开启。与 508 刻意区分：这一个你可以自行修复。
510	400	Email delivery needs a link to send, and a widget session has none - it returns a token for your backend to hand to the script. Omit email, or add a network for a direct-mode session, which returns a URL.	你让我们通过邮件发送一个没有 URL 的 connect 模式会话。请加上 `network`，或去掉 `email` 并自行交付会话。
511	400	The OAuth state parameter was not recognized. Start the social link again from your dashboard.	社交网络回调我们时携带了无法读取的握手值。请让你的用户重新发起连接。
512	403	The OAuth state parameter does not match this linking session. Start the social link again from your dashboard.	社交网络的回调属于另一个链接。请让你的用户从新的链接重新发起连接。
513	400	This session was minted for the hosted linking page, so it cannot open a single-network connect surface. Mint it with mode: “connect” instead.	只有你自己拼装 URL 时才会遇到。请打开端点返回的 `url`，而不要自行组装。

请按数字 code 匹配，而不要按消息文本——消息可能变化或被翻译。 其中哪些是你的页面能听到的。 设置了 origin 时，关联弹窗会向你的页面发送关联完成事件，513 可以以 connect:error 的形式到达。501、502 和 503 则不能：失效的链接在页面得知向哪里发送事件之前就被拒绝，因此你的用户会在屏幕上看到原因，而你的页面会在他们关闭窗口时听到 connect:cancelled。要区分这三者，请轮询获取 Link Session。504 到 510 是对 POST 本身的拒绝，绝不会以事件形式到达；511 和 512 在社交网络回调时产生，因此它们出现在那里，而不是你的页面上。

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 364 — X 速率限制（HTTP 429） X 对使用你的 BYO Key 发出的请求进行了限流。这是 Ayrshare 的通用速率限制错误码，现在也涵盖 X 评论读取路径：当 X 对读取进行速率限制时，Get Comments 会返回该错误码，而此前返回的是空的评论列表。

{
  "action": "rate limit",
  "status": "error",
  "code": 364,
  "message": "You are making too many requests. Please reduce the number of requests.",
  "platform": "twitter"
}

处理方式： 等待 X 的速率限制窗口重置后再重试。X 按 X 开发者应用计算限制，因此所有使用同一组 BYO Key 的 User Profile 发出的请求都会计入同一个限额。 Code 416 — X 额度耗尽（HTTP 402） 你的 X 开发者账号没有加载任何 API 额度。所有 X API 调用都需要额度，因此任何 X 路径都可能返回该错误码，包括发帖、分析以及 Get Comments 等读取操作。在评论路径上，它取代了此前返回的空评论列表，因此额度耗尽不会再被报告为帖子没有评论。 媒体上传也算作 API 调用。 当账号额度耗尽时，随 X 帖子发送图片或视频会返回 code: 416，因此 416 并不限于发布文本或拉取分析数据。上传会在帖子发布之前失败，并且不会重试——在账号充值额度之前，任何重试都不会成功。

{
  "status": "error",
  "code": 416,
  "message": "Your X Developer account has no API credits. Purchase credits at https://console.x.com (Billing → Credits). Even $5 is enough for hundreds of API calls.",
  "details": "Your enrolled X Developer account 1234567890 has no API credits. 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 499 — Ayrshare 媒体探测服务暂时不可用（HTTP 503） 当 Ayrshare 因内部媒体探测服务不可达或返回了无效响应而无法完成发布前的媒体检查时返回。这是 Ayrshare 服务侧的故障，并不表明你的媒体 URL、CDN、user-agent 规则或 robots.txt 配置存在问题。该错误携带 retryAvailable: true；请稍后针对失败的平台重试。如果多平台请求已部分成功，请只对 errors[] 中列出的平台重试，以避免产生重复帖子。

{
  "status": "error",
  "errors": [{
    "action": "post",
    "code": 499,
    "retryAvailable": true,
    "message": "Ayrshare's media probe service is temporarily unavailable. Please retry shortly.",
    "platform": "facebook"
  }]
}

Code 164 — Ayrshare 无法访问媒体（HTTP 400） Code 164 是一个沿用已久的媒体访问 / 输入类通用错误码，用于多种场景，包括 mediaUrls 格式错误、媒体无法读取，以及部分网络上传 / 抓取失败。请优先检查返回的 details。若为访问失败，请确认该 URL 可公开访问、在发布期间保持有效，并且未阻止远程请求。/media/urlExists 只执行 HEAD 可达性检查；即使该接口返回成功，也不能保证更深入的发布前媒体检查或社交网络的爬虫能够下载并处理该文件。当具体失败原因是 Ayrshare 自身的探测服务不可用时，你收到的会是可重试的 code 499，而不是 code 164。 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 媒体爬虫被阻止。

Threads 媒体尚未就绪

Code 522 — Threads 媒体尚未准备好发布 (HTTP 400) Ayrshare 尝试发布帖子时，Threads 尚未完成帖子的准备工作。Threads 可能会在真正接受发布的几秒钟之前就报告帖子已就绪。对于一篇 Threads 帖子，Ayrshare 会在多部分线程的所有部分中总共等待并重试最多 30 秒，之后才返回此错误，因此现在大多数此类帖子都能正常发布，不会出现任何错误。这通常是 Threads 方面的暂时性问题，并非你的内容所致。 Threads 评论、回复和首条评论也会获得同样的等待（首条评论会在帖子发布后单独获得 30 秒），但它们不会返回 code 522。对于多部分线程，code: 522 对象并不直接位于 errors 中：它是 Threads 错误中 posts 数组的最后一项，且上述 HTTP 400 状态仅适用于单篇 Threads 帖子。noAutoRetry: true 只会阻止 Ayrshare MCP 服务器自行重试该帖子；你仍然可以重试。

{
  "status": "error",
  "errors": [{
    "action": "post",
    "status": "error",
    "code": 522,
    "message": "Threads Error: Threads was not ready to publish this post, even after Ayrshare waited and retried. This is usually temporary. Please try posting to Threads again. https://www.ayrshare.com/docs/errors/errors-ayrshare#threads-media-not-ready",
    "retryAvailable": true,
    "noAutoRetry": true,
    "platform": "threads"
  }],
  "postIds": [],
  "id": "..."
}

处理方式： 你无需修改帖子。请先检查 postIds。如果没有任何内容发布，请使用 retry post 接口重试发布。如果同一帖子中的其他平台已经发布成功，请改为仅向 Threads 发送一篇新帖子：retry post 会将原始请求体重新发送到每一个平台，这会导致已成功的平台再次发布一遍。 多部分线程： postIds 为空并不能证明线程的任何部分都未上线。当后续部分失败时，Ayrshare 会删除已发布的部分，但如果删除失败，该部分会保留在 Threads 上。在重试多部分线程之前，请检查 Threads 账号并删除仍然存在的部分，否则重试会再次发布它们。

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 249 — Facebook 社区标准拦截（HTTP 400） 当 Facebook 依据其社区标准（Community Standards）拦截某条帖子时返回。拦截可能施加在 Facebook 账号或主页上，也可能施加在帖子本身上。Facebook 对这两种情况使用相同的底层错误，且不会说明属于哪一种。实际上，拦截最常施加在账号或主页上，因此改写或重新提交内容往往无济于事。与 Facebook 账号限制（code 476）一样，这是 Meta 侧的执法结果：它不可重试，也不会携带 retryAvailable 标记。首次违规时，账号仍与 Ayrshare 保持关联，不需要重新关联，重新关联也无法解除拦截。再次违规的情况则不同，详见下文。 Facebook 不通过 API 返回具体原因，因此客户必须直接在 Facebook 的 Account Status 页面查看原因并进行申诉。当 Facebook 提供了自己的原样文本时，Ayrshare 会将其放在 details 字段中。此外，Ayrshare 在检测到拦截时会向账号所有者发送一封通知邮件。如果同一 User Profile（用户资料）再次违反社区标准，Facebook 账号将与 Ayrshare 取消关联，且该 User Profile 将被暂停。

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 249,
      "message": "Facebook blocked this post under its Community Standards. The block is often placed on the Facebook account or Page rather than on the post itself, and Facebook does not return the specific reason through the API. Log in to Facebook, click your profile picture (top-right), open the Help section and select Account Status to see the reason and appeal.",
      "details": "...",
      "platform": "facebook"
    }
  ]
}

请根据数值 code 为 249 进行匹配，而不是根据 message 文本。message 的措辞可能会随时间调整，而错误码保持稳定。 处理方式： 登录 Facebook，点击右上角的头像，打开 Help 部分并选择 Account Status（账号状态）。Facebook 的支持助手会在此显示具体原因（API 不会返回该原因）并允许你申诉。请勿提示用户重新关联账号，因为重新关联无法解除账号级或主页级的拦截。完整的故障排除指南请参阅 Facebook 或 Instagram 账户被限制。

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、HEIF 与 AVIF 图片转换为 JPEG（WebP 转换适用于 Instagram、LinkedIn、TikTok、Google My Business、Threads 和 Snapchat；HEIC、HEIF 与 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 状态码来判断可重试失败。

当帖子面向多个平台时，重试前请先检查 postIds。只要有一个平台失败，整篇帖子就会被标记为错误，即使其他平台已经发布成功；而 retry post 会把原始请求体重新发送到该帖子的每个平台——这会让已成功的平台再发布一次。请改为针对 errors 中列出的平台发送一篇新帖子，只有在所有平台都未发布时才使用 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 缩略图未应用（未验证频道）。

Google Business Profile 授权错误

Code 519 — Google Business Profile 授权服务暂时不可用（HTTP 503） 当 Ayrshare 无法完成 Google 授权令牌刷新时返回，原因是 Google 的令牌接口响应缓慢或返回了瞬时失败。在返回此错误码之前，刷新会自动重试，且响应会带有 retryAvailable: true，因此集成可以基于该布尔字段而不是 HTTP 状态码进行分支处理。账号仍保持连接——这是 Google 授权服务的临时状况，并不是连接损坏。每个 Google Business Profile 操作都会先刷新授权，因此其中任何操作都可能返回此错误码——发布帖子、读取帖子历史、更新门店位置数据、获取已连接账号、列出评论以及回复评论。在这些路径上，大多数以前返回 code: 227 的响应现在会路由到 519 并带 retryAvailable: true。错误码 227 会要求用户重新连接账号，但这从来无法解决瞬时的刷新失败——授权本身自始至终是完好的。如果你的集成通过筛选 227 来提示重新关联 Google Business Profile，请改为在响应体上判断 retryAvailable 字段，并使用退避策略进行重试。

{
  "status": "error",
  "errors": [
    {
      "action": "authorization",
      "status": "error",
      "code": 519,
      "message": "Google Business Profile authorization service temporarily unavailable. Please retry.",
      "details": "<upstream reason, or the timeout summary>",
      "retryAvailable": true,
      "platform": "gmb"
    }
  ]
}

details 会包含 Google 报告的原因；当刷新在本地超时、Google 没有返回响应体时，则包含已尝试次数和已耗时的摘要。 处理方式： 使用指数退避重试该请求。请通过响应体上的 retryAvailable 字段而非 HTTP 状态码来判断可重试失败。

对于失败的跨平台帖子，请先检查 postIds 和 errors；如果其他平台已经发布成功，请只针对失败的 GMB 平台重试，而不要重新提交完整的请求体——retry post 会把原始请求体重新发送到该帖子的每个平台，这会让已成功的平台再发布一次。对于完全失败的帖子，你可以使用 retry post 接口重新提交相同的请求体。

Pinterest AI 披露警告

Code 521 — Pinterest AI 披露未应用（HTTP 200） 这是警告，而不是错误。 当 pinterestOptions.aiDisclosures 无效时返回，例如包含未知值或大小写错误。通过 REST API 时，不是字符串数组的值也会返回 521。Pin 仍会发布，但 Ayrshare 不会向 Pinterest 发送任何 AI 披露。MCP 服务器和 GraphQL API 会先检查值的类型，因此格式错误的值（例如包含数字的列表）会在发布前就被拒绝。该警告出现在 Pinterest 条目的 postIds[].warnings[] 上，而不是 errors[]，并携带 feature: "pinterestOptions.aiDisclosures"。可接受的值为 AI_MODIFIED 和 SYNTHETIC_PERFORMER。

Reddit 发布错误

Code 442 — Reddit Subreddit 被封禁（HTTP 400） 当账号已被禁止在目标 subreddit 发帖时返回。此错误不可重试——原样重新提交该帖子不会成功。消息中会包含受影响的 subreddit 名称（例如 r/news）。

{
  "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 524 — LinkedIn 令牌刷新被拒绝（HTTP 500） 当 LinkedIn 因应用的 LinkedIn 配置问题（而非用户账户问题）拒绝刷新授权时返回。用户的 LinkedIn 连接仍然有效，因此重新关联无法解决此问题。响应中不包含 resolution.relink 字段，并带有 retryAvailable: false，因为重试也无法解决此问题。任何先刷新授权的 LinkedIn 操作都可能返回此代码，例如在访问令牌过期后发布帖子。

{
  "status": "error",
  "errors": [
    {
      "action": "authorization",
      "status": "error",
      "code": 524,
      "message": "LinkedIn could not refresh the authorization. You do not need to relink LinkedIn. Please contact support.",
      "retryAvailable": false,
      "platform": "linkedin"
    }
  ]
}

处理方式： 请携带请求详情联系 Ayrshare 支持团队。不要要求用户重新关联 LinkedIn。重新关联没有帮助，而且在 LinkedIn 自身的设置中移除 Ayrshare 会撤销该用户在其连接的每个资料上的访问权限。

如果 LinkedIn 因临时原因持续刷新失败，Ayrshare 会进行重试，然后改为返回 code 119（“There was an issue connecting with LinkedIn. Please try again.”）。Code 119 可以安全地稍后重试；code 524 无法通过重试解决。

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" 的帖子，消息会改为指出视频未能发布，且相关操作不会执行。

过期或不可用的 Story 错误

Code 485 — Instagram / Facebook Story 评论以及 Instagram Story 分析（当作为代表性错误时映射为 HTTP 404） Story 在其可用时间窗口之后可能会过期或不可用。在该窗口之后，评论或洞察数据都无法被获取。错误码 485 用于标识：

来自 get-comments 的、已过期或不可用的 Instagram 与 Facebook Story 分支；以及
来自 POST /analytics/post 的、已过期或不可用的 Instagram Story 分支。

Facebook Story 分析不可用，也不在错误码 485 覆盖范围内。客户端应匹配数字型的 code，而不是精确的消息文本——后者可能变化或被翻译。在多平台读取中，如果至少有一个其他平台成功，失败的分支会出现在顶层的 errors[] 数组中，而健康平台会正常返回。整体响应为 HTTP 200，顶层 status: "partial"（参见评论的多平台读取与部分成功以及分析）。

Get Comments 部分成功示例

{
  "facebook": [
    {
      "comment": "What a great comment",
      "commentId": "806720068141593_1849585385469876",
      "created": "2026-07-14T19:55:28Z",
      "likeCount": 12,
      "platform": "facebook"
    }
  ],
  "status": "partial",
  "id": "Ut2fWU6XkqkMayHGnJZ7",
  "lastUpdated": "2026-07-14T22:30:13.035Z",
  "nextUpdate": "2026-07-14T22:41:13.035Z",
  "errors": [
    {
      "platform": "instagram",
      "status": "error",
      "code": 485,
      "message": "Instagram Story expired or unavailable — comments/insights cannot be retrieved.",
      "id": "17895695668004550"
    }
  ]
}

Post Analytics 部分成功示例

{
  "facebook": {
    "id": "1397547544885713_2159201585286968",
    "postUrl": "https://www.facebook.com/1397547544885713_2159201585286968",
    "analytics": {
      "commentsCount": 1,
      "likeCount": 23,
      "sharesCount": 12,
      "mediaView": 450
    },
    "lastUpdated": "2026-07-14T18:44:29.778Z",
    "nextUpdate": "2026-07-14T19:19:29.778Z"
  },
  "status": "partial",
  "id": "IHvCLacgPc6hMU9IQ6oK",
  "errors": [
    {
      "platform": "instagram",
      "status": "error",
      "code": 485,
      "message": "Instagram Story expired or unavailable — comments/insights cannot be retrieved.",
      "id": "17895695668004550"
    }
  ]
}

当所有平台都失败时，响应的顶层为 status: "error"，并包含完整的 errors[] 数组。代表性错误码 485 映射为 HTTP 404；其他代表性错误码使用各自的 HTTP 映射关系。 处理方式： 将错误码 485 视为一个信号——所请求的 Story 评论或洞察数据无法被获取。请基于该错误码进行匹配，而不要从消息文本中推断出永久失败、可重试性或账户关联状态等结论。

错误消息翻译

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

"Translate-Error-Message": "Language_Code"

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

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

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

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

错误处理

每月发帖配额

重复与相似内容错误

Instagram 专属错误码

可重试（Retry Available）

Instagram Reels 音频错误

自动化私信回复（评论 DM）错误

线程与媒体选项错误

Link Session 错误

X/Twitter BYO Key 错误

文案增强错误

媒体抓取 / 爬虫访问错误

Threads 媒体尚未就绪

Facebook 分析速率限制

Meta 身份验证

Facebook 社区标准拦截

Facebook 账号限制

图片格式转换错误

YouTube 瞬时上传错误

YouTube 缩略图错误 Code 307

Google Business Profile 授权错误

Pinterest AI 披露警告

Reddit 发布错误

内容审核错误

LinkedIn 授权刷新错误

LinkedIn 分析错误

TikTok 评论错误

过期或不可用的 Story 错误

Get Comments 部分成功示例

Post Analytics 部分成功示例

错误消息翻译

​错误处理

​每月发帖配额

​重复与相似内容错误

​Instagram 专属错误码

​可重试（Retry Available）

​Instagram Reels 音频错误

​自动化私信回复（评论 DM）错误

​线程与媒体选项错误

​Link Session 错误

​X/Twitter BYO Key 错误

​文案增强错误

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

​Threads 媒体尚未就绪

​Facebook 分析速率限制

​Meta 身份验证

​Facebook 社区标准拦截

​Facebook 账号限制

​图片格式转换错误

​YouTube 瞬时上传错误

​YouTube 缩略图错误 Code 307

​Google Business Profile 授权错误

​Pinterest AI 披露警告

​Reddit 发布错误

​内容审核错误

​LinkedIn 授权刷新错误

​LinkedIn 分析错误

​TikTok 评论错误

​过期或不可用的 Story 错误

​Get Comments 部分成功示例

​Post Analytics 部分成功示例

​错误消息翻译

错误处理

每月发帖配额

重复与相似内容错误

Instagram 专属错误码

可重试（Retry Available）

Instagram Reels 音频错误

自动化私信回复（评论 DM）错误

线程与媒体选项错误

Link Session 错误

X/Twitter BYO Key 错误

文案增强错误

媒体抓取 / 爬虫访问错误

Threads 媒体尚未就绪

Facebook 分析速率限制

Meta 身份验证

Facebook 社区标准拦截

Facebook 账号限制

图片格式转换错误

YouTube 瞬时上传错误

YouTube 缩略图错误 Code 307

Google Business Profile 授权错误

Pinterest AI 披露警告

Reddit 发布错误

内容审核错误

LinkedIn 授权刷新错误

LinkedIn 分析错误

TikTok 评论错误

过期或不可用的 Story 错误

Get Comments 部分成功示例

Post Analytics 部分成功示例

错误消息翻译