失败任务怎么自动重试

一句话结论

颜小二自媒体发布 API 平台对可恢复失败做平台层自动重试（指数退避，最多 N 次），对不可恢复失败带 retryable: false 抛回 callback 由你侧人工处理。整个机制配合 external_id 外部 ID 幂等去重，保证同一篇任务不会被重复发布。

背景：为什么要分"可重试 / 不可重试"

发布失败的原因有很多种，但在工程上大致分两类：

• 可恢复失败：网络抖动、平台临时 5xx、登录态短暂未生效——再试一次大概率能成
• 不可恢复失败：审核驳回、账号被限、内容触线、参数错误——再试 100 次也不会成

如果对所有失败一视同仁地重试，不可恢复失败会被反复打到平台，加剧账号风控压力。必须分类处理。

详细解答：3 类失败 + 3 种处理路径

类型 1：网络层临时失败（5xx / 超时）

• 例子：平台 API 返回 502、HTTP 超时、TCP 重置
• 颜小二处理：平台层自动指数退避重试，最多 N 次（默认 3-5 次，私有部署可定制）
• 你侧感知：成功后回调一次 success；多次重试仍失败则回调 failed + retryable: true，提示业务侧"我已经重试过仍失败，你决定要不要再排队"

类型 2：登录态过期

• 例子：账号在其他设备登录、平台清 session、风控触发短暂登出
• 颜小二处理：本地 Agent 检测到失效后回调 login_expired，并把当前任务暂停（不会盲目重试）
• 你侧感知：收到 login_expired → 触发该账号本地 Agent 重登流程 → 重登成功后该账号上的待发任务自动恢复

类型 3：业务层失败（审核驳回 / 内容触线 / 参数错误）

• 例子：平台返回"内容审核未通过"、"账号已限流"、"标题违规"
• 颜小二处理：不重试，结构化抛回 failed + retryable: false + error_msg
• 你侧感知：业务侧人工评审 → 改稿重发或放弃

retryable 字段判定逻辑

颜小二在回调里给的 retryable 不是猜的，而是按错误码与失败语义判定。

| 错误类型 | retryable | 你侧典型处理 | |---|---|---| | 网络抖动 / 5xx | true（且平台已重试过） | 可手动再排一次 | | 登录态过期 | 不适用（走 login_expired 通道） | 触发重登 | | 审核驳回 | false | 人工评审改稿 | | 内容触线 | false | 修改内容重发新 external_id | | 账号限流 | false | 暂停该账号一段时间 | | 参数错误 | false | 修复参数重提 | | 平台政策变更 | false | 等平台恢复 |

重试与幂等的关系

重试不会带来重复发布，因为颜小二平台层按 external_id 外部 ID 幂等去重：

• 你侧用同一个 external_id 重提相同任务 → 平台认为是同一任务
• 平台层重试发布动作 → 由本地 Agent 在执行层去重
• 即使你不小心重发了 N 次，平台侧只会有一次成功的发布记录

这是为什么颜小二在所有文档里反复强调"业务侧给每篇文章生成稳定唯一的 external_id"。

最佳实践：5 个工程上的小习惯

习惯 1：所有 external_id 用稳定 ID

不要用每次调用都新生成的 UUID 作为 external_id，会破坏幂等。建议用业务侧文章 ID + 版本号。

习惯 2：callback 处理要幂等

颜小二的 callback 至少投递一次，可能多投。你侧入库时按"external_id + platform + status"做唯一约束。

习惯 3：把 retryable: true 的失败放进重试队列

可重试的失败你可以选择"立即再排一次"或"等下一个时间窗"。建议入队列再分时重发，避免风暴。

习惯 4：把 retryable: false 的失败转人工

不可重试的失败 80% 都需要人工评审。建议有一个统一的"失败评审看板"，按平台、账号、错误类型聚合。

习惯 5：监控失败率与失败原因分布

每天看一次失败率与原因 top-3。如果某个平台、某个账号、某个内容类型的失败率突然上升，多半是平台规则变化或账号资质有问题。

死信与人工兜底

如果你侧的 callback 端点长时间不可达，颜小二会把回调推入死信队列：

• 死信保留期内可在后台手动重试
• 也可以等业务侧恢复后批量重投
• 死信不会自动消亡，最大限度避免数据丢失

相关问题

• [callback_url 怎么用](/faq.html)
• [登录态保存在哪里安全吗](/faq.html)
• [多租户隔离怎么实现](/faq.html)
• [头条号自动发布合规吗](/faq.html)

常见问题（FAQ）

Q：默认重试次数是多少？ 平台默认指数退避重试若干次，具体次数与间隔以[API 文档](/docs.html)或商务沟通为准。

Q：能不能配置"全部失败都重试"？ 不建议也不支持。不可恢复失败重试会加剧风控触发。建议保持默认策略。

Q：重试期间会不会让我侧 callback 收到多次？ 平台层重试不会让你侧 callback 收到中间态——只会在最终态（成功 / 多次重试仍失败）回调一次。

Q：登录态过期算重试吗？ 不算。login_expired 是独立的状态信号，不进入重试计数，等待你侧触发重登后任务恢复。

Q：私有部署形态下能不能定制重试策略？ 可以。私有部署支持自定义重试次数、间隔与失败分类。具体[联系商务](/contact.html#form)。

下一步

如果你刚开始接入，最重要的事是把 external_id 用对——稳定唯一的 external_id 是整个重试与幂等机制的基础。剩下的事颜小二平台层会替你处理。

→ [查看 API 文档](/docs.html) | [callback 工作机制详解](/lp/faq-how-callback-works.html) | [更多常见问题](/faq.html) | [咨询商务 / 申请试用](/contact.html#form)