跳转到主要内容
在适用时,REST API 会在响应中包含一个错误列表。
错误响应的返回状态码可能为 400、401、402、403、404、429、500、502、503 或 504。成功时返回状态码为 200。详情参见此处。
每次 API 调用返回的错误可能不同,具体取决于该请求以及在社交网络上遇到的问题。 错误响应会包含 API 调用出错的详细信息。 例如,一条被 Twitter 和 Facebook 判定为重复的帖子会返回如下响应。
请注意:
  • errors 字段包含错误数组,每个出错的社交网络对应一条错误。
  • action 指的是所返回错误的类型。
  • 如果 API 调用失败,顶层 status 字段会是 “error”。例如,对于 /post 调用,如果所有社交网络发布都成功,status 字段会是 “success”;否则, status 字段会是 “error”。
  • code 字段包含 Ayrshare 的参考错误码。
  • message 字段是该错误的具体细节。

错误处理

你应对任何错误响应进行处理并采取相应操作。发生错误的情况包括:
  • 响应返回码不是 200
  • JSON 响应的 status 为 error
例如,如果你的用户移除了 Facebook 关联——他们修改了密码,或撤销了 Ayrshare 的访问权限——发帖时会得到下面这样的响应,HTTP 返回码为 400 Bad Request。
对应的处理可能是通过你的控制台、短信或邮件通知你的用户。 另一个例子是,如果发布到 Instagram 的图片尺寸或比例不正确,会返回带 400 Bad Request 的响应码:
对应的处理可能是以正确的比例重新提交图片。

每月发帖配额

Code 106 — 超出每月发帖配额(HTTP 429) 该资料已用完其每月发帖配额。/post 会对新的发帖请求返回此错误,包括将帖子排期的请求。其他帖子相关请求(例如获取、删除或重试帖子,或帖子分析)在配额重置前也会返回此错误。在配额用完期间到期的已排期帖子也会以此代码失败。这不是速率限制,等待几分钟也无济于事。 通常,整个响应就是该错误:
对于已排期的帖子,同样的错误会出现在该帖子的 errors 数组中。如果在发送新帖子的过程中配额用完,新帖子也可能出现这种情况。请在这两处都检查 code: 106。 处理方式: 通过 User Profile 详情 查看 monthlyPostCount 和 monthlyPostQuota。配额在每月 1 日(UTC)重置。更改计划会立即重置你的 Primary Profile 的计数。失败的发帖尝试也会计入,因此请停止对持续失败的帖子进行自动重试。详情请参见我可以发布多少帖子和调用多少 API?。

重复与相似内容错误

在帖子发送到社交网络之前,Ayrshare 会将其与你的其他帖子进行比对,并以代码 137 拒绝完全相同或高度相似的内容。这是 Ayrshare 自己的检查,因此即使社交网络本身会放行,帖子也可能被拒绝。该检查并不覆盖所有平台——请参阅下文的例外情况。
检查窗口。 每个帖子都会在以其自身 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。
处理方式: 等待速率限制窗口重置后再重试。当 Meta 提供了 Retry-After header 时,其值(以秒为单位)会通过 details 字段传递——至少等待相应时长再重新提交。 Code 436 — Instagram 媒体处理超时(HTTP 400) Instagram 处理上传的媒体耗时过长。这可能发生在大视频文件上,或在 Meta 服务器高负载时。
处理方式: 使用 retry post 接口重试发布。如果问题持续存在,请尝试减小媒体文件大小。 Code 447 — Instagram Trial Reels:缺少 graduationStrategy(HTTP 400) 当 /post 请求中提供了 instagramOptions.trialParams,但 graduationStrategy 缺失、为 null 或为空字符串时返回。Trial Reels 需要明确的 graduation 策略——参见 Trial Reels。
处理方式: 将 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 个字符)以便调试。
处理方式: 将 graduationStrategy 严格以 "MANUAL" 或 "SS_PERFORMANCE" 的形式发送(全大写、字符串类型)。 Code 449 — Instagram Trial Reels:媒体不兼容(HTTP 400) 当媒体或帖子形态不满足 trial reel 要求时返回。Trial Reels 必须是单个 .mp4 或 .mov 视频——轮播(多个 URL)、Story(instagramOptions.stories: true)以及非视频后缀都会被拒绝。details 字段会说明是哪种子情况触发。
处理方式: 提交单个 .mp4 或 .mov 视频 URL,且不设置 stories: true。去掉多余的 mediaUrls 条目,或者如果你原本想发的是普通轮播 / Story 帖子,请移除 trialParams。 Code 258 — Instagram 账号状态错误(HTTP 400) Instagram 账号状态相关的通用失败,基础消息为 “Error with Instagram.”。当 Meta 因所连接的 Instagram 账号状态(而非帖子内容)拒绝请求时会出现该错误。
当底层的 Meta error_subcode 为 2207085(“Generic Internal Error”,通用内部错误)时,这是 Meta 侧的临时故障。Ayrshare 会自动重试发布,最长约 50 秒,然后才返回该错误,响应中会设置 retryAvailable: true,但不会设置 relink: true —— 重新关联账号无法解决这种情况。当 Meta 返回 fbtrace_id 时,该值会包含在 details 中:
处理方式: 对于 2207085 子情况,请在几分钟后重试发布 —— 这是 Meta 侧的状况,通常会自行恢复,重新关联账号并不能解决。仅当错误持续超过 24-48 小时时,才提示用户在 Social Accounts 页面解除并重新关联其 Instagram 账号,授予所有请求的权限,或携带 details 中的 fbtrace_id 联系 Meta 支持。对于其他账号状态错误,请先在 Meta 侧确认 Instagram 账号状态正常后再重试。

可重试(Retry Available)

有时社交网络会遇到无法自动恢复的错误(例如它们的服务器出问题),即便经过多次重试,调用最终仍然失败。 在这些情况下,我们的系统会判断该错误是否可重试,如可重试,retryAvailable 字段将为 true。
之后你可以使用相同的请求体重试该调用。 如果是发帖,可以使用 retry post 接口。

Instagram Reels 音频错误

这些错误码涉及使用 instagramOptions.audioConfiguration 为 Instagram Reel 附加音乐,以及音频搜索和音频查询端点。
代码 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)错误

当携带私信的私信回复无法发送时,这些错误码会出现在 Instagram 和 Facebook 主页上评论触发的自动化(comment_keyword)中。它们会以活动条目 status: "failed" 出现,原因位于 actionResults[].errorDetails。 它们都不会被自动重试——Meta 的 Send API 没有幂等键,自动重试可能导致该私信被投递两次。不同错误码的处理方式不同(见下方 处理方式):大多数对于该特定评论是永久性的;492 需要重新关联账户;493 会随每小时限额重置而自行恢复。
代码 491 涵盖 Meta 不加区分的多种原因,而 490 是狭窄的例外。 Meta 对以下情况返回同一个共用错误:评论超过 7 天、评论已经收到过回复(每条评论只允许一条私信回复)、评论已被删除、评论者屏蔽了消息请求。以上所有情况都会报告 491。490 仅在 Meta 直接将评论 ID 判定为无效,而不是返回上述共用类别时才会出现——因此一条被删除的评论可能报告为 490 或 491,取决于 Meta 返回的是哪一个。由于 API 并不区分这些情形,请始终读取 errorDetails:其中携带平台自身的原文,通常对原因说明得较为具体。
代码 489 已被保留,目前不会返回。 它被留给”该评论已存在回复”的情形,Meta 目前不将其作为一个独立信号公开——今天该情形报告为 491。之所以列在此处,是为了避免该编号被复用。
真正过期或失效的连接不在此范围内。 如果所存储的 Instagram 或 Facebook 主页凭据已过期,活动条目会为 status: "auth_error" 而不是 failed,正确的解决方式是重新关联账户。除 492(缺少权限,需重新关联账户以授予)之外,上述代码都是评论层面的条件,绝不表示”需要重新关联”。
依据你从哪里读取,这些错误码会以两种不同的形态出现,而携带平台原因的字段在两种形态下的名称也不同。 1. 在自动化活动条目上 —— 即 GET /automations/:id/activity 返回的内容。平台的原因位于 actionResults[].errorDetails:
2. 作为直接 API 错误封装 —— 标准的错误结构,其中同样的原因位于 details:
对于评论触发的自动化,你几乎总是在读取形态 1。那里的 errorDetails 与封装中 details 携带的是同一个字符串。 处理方式:
  • 490、491、495 —— 属于每条评论级别的条件。对于该特定评论无法恢复,任何重试都无济于事;在下一条新评论上,自动化会正常运行。请阅读 errorDetails 查看平台给出的原因。
  • 492 —— 重新关联 Instagram 账户或 Facebook 主页,并授予所有请求的权限。这是账户级别的修复,否则会影响每一条评论。
  • 493 —— 除等待外无需任何操作;每小时限额会自行重置。不会自动重试,因此该评论对应的私信不会被发送。
  • 494 —— 内部配置错误,不属于客户侧问题。如果反复出现,请联系支持。
sent 状态并不保证已投递。 除了上述失败之外,Instagram 接受的私信回复(status: "sent")仍然可能在收件人的 Instagram Message requests 设置屏蔽陌生人时被静默丢弃——这种情况根本不会产生错误码。请参见自动化私信已发送但未送达。

私信投递无法确认

代码 529:无法确认消息投递(HTTP 502) 当社交网络返回未知错误,且 Ayrshare 之后无法在会话中找到该消息时,Instagram 和 Facebook 上的发送消息会返回此错误码。如果找到了该消息,你会收到带有其 messageId 的正常成功响应,因此此错误码仅表示投递未经确认,并不表示消息发送失败。它携带 retryAvailable: false,并且重新关联无济于事,因为账户连接是正常的。
处理方式: 不要立即重新发送,因为该消息可能已经在会话中,重新发送会导致它被发送两次。请等待 messages webhook,如果消息已发送,它会报告该消息。如果你改为使用获取消息进行检查,请在出现错误后至少等待 60 秒:其结果最多会缓存一分钟,因此过早检查可能会遗漏已投递的消息。仅在消息不存在时才重新发送。

私信发送被暂时阻止

代码 530:账户被暂时阻止发送消息(HTTP 429) 当社交网络暂时阻止该账户发送消息时,Instagram 和 Facebook 上的发送消息会返回此错误码。消息未被发送。账户连接是正常的,因此重新关联无济于事。社交网络给出的原因位于 details。最常见的情况是该账户在短时间内发送了大量消息,但社交网络也可能因消息内容或政策而阻止消息。
处理方式: 阅读 details,不要立即重新发送同一条消息。
  • 如果它表示该账户被暂时阻止执行此操作(如上例所示),请暂停从该账户发送消息,并在恢复后降低发送频率。立即重试会使账户被阻止的时间更长。阻止持续多久由社交网络决定,且不会公开。
  • 如果它指向消息内容或政策,请在再次发送之前修改该消息。

线程与媒体选项错误

当某个选项无法应用于帖子时会返回这些错误码——最常见于 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 添加你自己的 线程分隔符在这里无济于事——每个 分隔符都会创建另一条帖子,因此可能使数量进一步超出限制。
  • 527:twitterOptions.mediaUrls items must be a URL string, null, or an object of URL strings. Use an object, not an array, to add multiple media to one thread part. 当线程 mediaUrls 中的某一项是数组、数字或其他不允许的内容时,会返回此错误并附带 HTTP 400。 不会发布任何内容。details 字段会指出需要修正的第一项,例如 twitterOptions.mediaUrls[0]。处理方式: 将该项改为 URL 字符串、null 或由 URL 字符串组成的对象,然后重新发送帖子。 如需为线程的某一部分添加多个媒体对象,请发送 [{ "a": "urlA", "b": "urlB" }],而不是 [["urlA", "urlB"]]。请参见 允许的 mediaUrls 项。
  • 528:Platform options cannot contain an array inside an array. See details for the field to fix. 当任何平台选项对象(例如 instagramOptions 或 youTubeOptions)中有数组直接嵌套在 另一个数组中时,会返回此错误并附带 HTTP 400。不会发布任何内容。details 字段会给出需要修正的 字段路径,例如 instagramOptions.collaborators[1]。处理方式: 将该字段展平为单个数组,或使用该选项在其平台页面上所示的结构,然后重新发送帖子。
你的账户无法使用的选项会导致整条帖子失败,而不是被忽略。对线程而言,这意味着线程的 任何部分都不会发布——已经发出的部分会为你自动删除。删除是尽力而为的:如果社交网络拒绝 删除操作,该部分可能仍保持已发布状态,因此请检查线程并移除任何遗留内容。此前这些选项 中的一部分在线程上会被静默丢弃,线程在不带它们的情况下照常发布。
错误码 501 到 513 属于社交关联:使用创建 Link Session 创建链接,以及打开链接。它们携带 "action": "link session"。本页上其他 500 系列错误码与此无关 ——514 到 518 是 Instagram Reels 音频。 请按数字 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 117 - 媒体上传错误(HTTP 403) 媒体文件无法上传到 X。可能是 X 拒绝了该文件,也可能是 Ayrshare 无法处理它。Threads 和 Snapchat 的媒体检查也可能返回此错误码。
当 X 发送其自身的错误文本时,details 会携带该文本。对于某些 X 响应,message 也会变为简短的 X 媒体错误。请先阅读 details,它是找出真正原因的最佳线索。 处理方式: 对照 X 媒体指南检查文件的大小、尺寸和内容类型。如果媒体没有问题,且同一请求中发布到其他社交网络的帖子都成功了,请检查你的 X 开发者账号的计费情况。额度耗尽和支出上限问题现在会返回 code 416,而不是 117。 Code 272 - 无法验证 BYO Twitter 身份(HTTP 400) Ayrshare 无法通过你的 BYO consumer keys 以及关联时保存的 OAuth token 确认你的 X/Twitter 身份。响应结构会根据触发它的调用有所不同;两种形式都对应下面同样的三种子情况。请使用拥有 BYO 开发者应用的账号登录 x.com 来判断具体是哪一种。 发帖路径返回的是最小化响应:
分析路径返回的是更详尽、更具自描述性的消息,可能还包含一个 details 字段,携带 X 的原始错误字符串:
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 会返回该错误码,而此前返回的是空的评论列表。
处理方式: 等待 X 的速率限制窗口重置后再重试。X 按 X 开发者应用计算限制,因此所有使用同一组 BYO Key 的 User Profile 发出的请求都会计入同一个限额。 Code 416 — X 额度耗尽或已达支出上限(HTTP 402) 由于你的 X 开发者账号存在计费问题,X 拦截了该请求。该错误码涵盖两种情况:
  • 没有额度。 你的 X 开发者账号没有加载任何 API 额度(X 返回 HTTP 402)。
  • 已达支出上限。 你的 X 开发者账号已达到每月支出上限(X 返回 HTTP 403)。X 会设置默认支出上限,因此即使你没有自行设置,也可能触发。
两种情况下 Ayrshare 都返回 HTTP 402。请查看 message 判断属于哪种情况。 所有 X API 调用都会计费,因此任何 X 路径都可能返回该错误码,包括发帖、分析以及 Get Comments 等读取操作。在评论路径上,它取代了此前返回的空评论列表,因此计费拦截不会再被报告为帖子没有评论。 媒体上传也算作 API 调用。 当账号额度耗尽或超出支出上限时,随 X 帖子发送图片或视频会返回 code: 416,因此 416 并不限于发布文本或拉取分析数据。上传会在帖子发布之前失败,并且不会重试——在计费问题解决之前,任何重试都不会成功。 没有额度:
处理方式: 前往 console.x.com → Billing → Credits 购买额度。即使 $5 也足够支持数百次 API 调用。 已达支出上限:
处理方式: 前往 console.x.com → Billing,提高或重置每月支出上限。支出上限与额度余额相互独立,请同时检查两者。X 会在先达到的那个限制处停止。 Code 417 — OAuth 1.0a 应用权限(HTTP 403) 你的 X Access Token 没有目标操作所需的正确权限。
你可能还会看到响应头 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 都缺失时:
当只提供了其中一个时(例如只提供 key 而未提供 secret):
处理方式: 在每一个指向 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 开发者应用凭证。
处理方式: 配置一个 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[] 视为互为补充,而非互斥关系。
如果所有平台的增强都失败,响应会是顶层 code: 441,HTTP 502,且不会创建任何帖子:
处理方式: 文案增强失败通常是瞬时的(底层的短链或增强服务返回了错误)。
  • 如果 postIds 非空(部分平台已成功发帖),不要重新提交完整的平台列表——那会在已成功的平台上产生重复帖子。请改为查看 errors[] 找出失败的平台,只针对这些平台重试,或使用你自己的幂等重试流程。
  • 如果 postIds 为空或缺失(在排期 / 发帖阶段完全失败),可以安全地重试整个请求。
  • 如果问题持续,请去掉增强标志重新发布(例如去掉 shortenLinks),或联系支持团队。

媒体抓取 / 爬虫访问错误

Code 499 — Ayrshare 媒体探测服务暂时不可用(HTTP 503) 当 Ayrshare 因内部媒体探测服务不可达或返回了无效响应而无法完成发布前的媒体检查时返回。这是 Ayrshare 服务侧的故障,并不表明你的媒体 URL、CDN、user-agent 规则或 robots.txt 配置存在问题。该错误携带 retryAvailable: true;请稍后针对失败的平台重试。如果多平台请求已部分成功,请只对 errors[] 中列出的平台重试,以避免产生重复帖子。
Code 164 — Ayrshare 无法访问媒体(HTTP 400) Code 164 是一个沿用已久的媒体访问 / 输入类通用错误码,用于多种场景,包括 mediaUrls 格式错误、媒体无法读取,以及部分网络上传 / 抓取失败。请优先检查返回的 details。当 Ayrshare 的发布前媒体检查能够判断媒体失败的原因时,message 会在 “Error accessing the media.” 之后说明原因:媒体主机返回了 HTTP 403(它正在阻止该请求)、404、其他 4xx 或 5xx 错误,或者文件已下载但无法读取,例如不完整或无效的 MP4/MOV 视频。请修复 message 中指出的原因。若为访问失败,请确认该 URL 可公开访问、在发布期间保持有效,并且未阻止远程请求。/media/urlExists 只执行 HEAD 可达性检查;即使该接口返回成功,也不能保证更深入的发布前媒体检查或社交网络的爬虫能够下载并处理该文件。当具体失败原因是 Ayrshare 自身的探测服务不可用时,你收到的会是可重试的 code 499,而不是 code 164。 Code 479 - 社交网络无法抓取媒体 / 爬虫被阻止(HTTP 400) 专用的不可重试错误码,当 Meta 无法从提供的 URL 抓取媒体时返回,即使 Ayrshare 已作为备用方案将其重新托管到自己的 CDN 上。这表明主机正在通过 robots.txt 或 CDN / WAF 规则阻止 Meta 的爬虫(facebookexternalhit / Facebot),或者源站在服务器端无法访问。对应 Meta/Instagram 子代码 2207052。 由于 Ayrshare 的 CDN 重新托管备用方案已经尝试过且同样失败,重试无济于事,需要在托管端进行修复(允许 Meta 的爬虫访问,或从可访问、未被阻止的主机提供媒体)。此错误携带 retryAvailable: false。
处理方式: 完整的排查方式(包括 robots.txt 片段与一个验证命令)请参见 Meta 媒体爬虫被阻止。 Code 440 - Instagram 无法接收媒体(暂时性,HTTP 400) 针对真正暂时性的 Meta 媒体接收问题返回,即 Meta/Instagram 子代码 2207032(“download too slow”)/ 2207003(“create media fail”),或未分类的接收重试耗尽,在 Meta 经过多次内部重试仍未能接收该媒体之后返回。与 code 479 不同,此错误可以通过 /post/retry 重试。 如果失败原因是主机端的爬虫阻止或源站无法访问(子代码 2207052,且 Ayrshare 的 CDN 重新托管备用方案也失败了),你收到的将是 code 479,详见上文。 对于暂时性的接收失败,retryAvailable 为 true;少数 440 情况(例如源媒体超出大小限制)会返回 false。
Code 138 — Instagram 媒体抓取被阻止(HTTP 400) 当上游响应不如触发 code 479 的情况那样具体时,Instagram 媒体抓取失败的备用错误码。details 字符串通常包含 "Restricted by robots.txt" 或 "HTTP error code 403"。Code 138 还用于宽高比 / 格式问题以及其他通用 Instagram 错误,因此可以通过 details 字符串来识别”媒体抓取”这一变体。当阻止被确认为主机端爬虫阻止(子代码 2207052)时,你通常会看到专用的 code 479;暂时性的接收失败请参见 code 440。
Code 379 — Threads 发布错误 当 Threads 发布失败时返回。最常见的原因是使用相同的 mediaUrl 同时发布到两个平台时,出现与 code 479 / 138 相同的媒体抓取问题。Threads API 不会返回详情字符串,因此诊断通常需要检查同一次发布中是否同时出现了 Instagram 错误:Instagram 上的 479(主机端爬虫阻止 / 源站无法访问)或 440(暂时性接收问题)通常就是信号。
处理方式: 完整的排查方式(包括 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 服务器自行重试该帖子;你仍然可以重试。
处理方式: 你无需修改帖子。请先检查 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:
处理方式: 等待几分钟后重试。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 侧完成验证。 账号所有者完成验证后,请重试请求。当该账号发起请求时,Ayrshare 会自动向 Meta 确认验证状态,每个平台通常最多每 15 分钟确认一次;如果 Meta 出现临时错误,则会更早确认(约 1 分钟后)。如果 Meta 确认验证已完成,请求将正常执行。 在已知时,错误还会包含以下时间字段,均为 ISO 8601 字符串:
  • lastCheckedAt:Ayrshare 上次向 Meta 确认的时间。
  • nextCheckAt:Ayrshare 可以再次确认的时间。请在此时间之后重试。如果没有该字段,请过一段时间后再重试。
处理方式: 请账号所有者前往 Meta Business Support 完成 Meta 的身份验证,然后在 nextCheckAt 之后重试请求。如需立即确认,请在控制台的 Social Accounts 页面点击 Check Again。请勿提示用户重新关联账号——重新关联并不会消除该验证要求。

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 将被暂停。
请根据数值 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 在检测到限制时会向账号所有者发送一封通知邮件。
处理方式: 登录 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。最常见的原因是源文件损坏、容器内的内部格式异常,或图片超出了转换的大小上限。
处理方式: 直接在浏览器中打开该 mediaUrl,确认它能正常渲染。如果可以,请重新导出为干净的 JPEG 或 PNG 后重试发布。 Code 451 — 转换所需的图片下载失败(HTTP 400) 转换流水线无法获取源图片。常见原因包括来源返回 4xx/5xx、网络超时、重定向链超过跳数上限,或 URL 解析到了非公开地址(被 SSRF 防护阻止)。details 字段(若存在)会携带底层的原因字符串。
处理方式: 确认 mediaUrl 可公开访问(不需要认证,不被 robots.txt 屏蔽,可通过 HTTPS 解析)。如果 URL 存在重定向,请确保最终目的地也是公开的且不在私有网络内。 Code 452 — 转换后图片上传失败(HTTP 500) 转换成功,但 Ayrshare 无法将转换后的 JPEG 暂存到其临时存储桶。这是 Ayrshare 侧的内部故障,可重试。
处理方式: 重试发布。如果多次重试后错误依然存在,请携带 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 流水线在接收上传时超时时返回。这通常是瞬时性的,会在一两分钟内自行恢复。
处理方式: 使用指数退避在 1–2 分钟后重试。请通过响应体上的 retryAvailable 字段而非 HTTP 状态码来判断可重试失败。你可以使用 retry post 接口重新提交相同的请求体。 Code 454 — YouTube 上传服务暂时不可用(HTTP 503) 当 YouTube 上传接口返回 5xx 状态、或到 YouTube 的连接在 socket 层被重置或超时(ECONNRESET、ETIMEDOUT、ESOCKETTIMEDOUT)时返回。这些情况都是瞬时的。
处理方式: 使用指数退避重试该请求。请通过响应体上的 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 账号。
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 字段,并使用退避策略进行重试。
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)。
处理方式: 从目标 subreddit 列表中移除该被封禁的 subreddit。原样重试该帖子不会成功。 Code 443 — Reddit 标题包含禁用词(HTTP 400) 当某个 subreddit 因帖子标题包含禁用词而拒绝该帖时返回。请在重试前修改标题——原样重新提交不会成功。消息中会包含受影响的 subreddit 名称(例如 r/news)。
处理方式: 编辑帖子标题以去除该禁用词,然后重试。

内容审核错误

Code 438 — 审核输入被拒(HTTP 400) 当 AI 提供方拒绝所提供的输入时(例如不支持的文件类型),由 POST /validate/moderation 返回。这是请求输入本身的问题,而非瞬时的处理失败。
处理方式: 确认审核输入有效并使用受支持的文件类型,然后重新提交。
将 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 操作都可能返回此代码,例如在访问令牌过期后发布帖子。
处理方式: 请携带请求详情联系 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 拒绝该分析请求。发帖不受影响。
处理方式: 请账号所有者在 Social Accounts 中重新关联其 LinkedIn 资料以授予新的分析作用域,然后重试分析请求。重新关联后,请预留几分钟让该错误消退:Ayrshare 会短暂缓存此错误,同时 LinkedIn 也会缓存 token 的权限,因此重新关联的资料在分析恢复之前可能仍会返回约 5–10 分钟的 475。

TikTok 可用性错误

代码 531:TikTok 暂时不可用(HTTP 503) 当 Ayrshare 读取 TikTok 账户时,如果 TikTok 暂时不可用或每次尝试都无法连接(例如 TikTok 短暂中断期间),将返回此代码。Ayrshare 在返回此代码之前至少会重试一次。TikTok 连接仍然有效,因此重新关联无济于事。响应中包含 retryAvailable: true。 任何会先刷新账户访问令牌的 TikTok 请求都可能返回此代码,例如发布帖子、评论或 Analytics on a Social Network。
处理方式: 使用指数退避进行重试。对于发送到多个网络的帖子,其他网络可能已经发布,因此请检查 postIds 和 errors,并使用 retry post 端点仅重试 TikTok,而不是重新发送整个帖子。不要要求用户重新关联 TikTok。当连接本身需要处理时,仍会返回代码 263(“Error connecting with TikTok”)。

TikTok 评论错误

Code 288 — TikTok 评论被延后 / 帖子仍在处理中(HTTP 400) TikTok 异步处理视频,因此在 TikTok 的 post.publish.publicly_available webhook 解析出真实的视频 ID 之前,新发布帖子的 id 会是 "pending"。对仍在处理中的帖子(或 id 为 "failed" 的帖子)发起的获取评论、评论或回复请求会在调用 TikTok 之前被拒绝,并返回 code 288,而不是一个通用失败。
处理方式: 等待 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 部分成功示例

Post Analytics 部分成功示例

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

错误消息翻译

API 错误消息响应可以自动翻译为你选择的语言。 如果你想直接以用户偏好的语言向他们展示错误,这非常有用。 如果你想选择社交关联页面的语言,请参见此处。 在 header 中加入:
其中 Language_Code 是可用的语言代码之一。 例如,以下代码会将错误翻译为法语。
我们的系统会自动检测错误消息的语言。