Error Handling Guide
Search 和 lookup 工作流里的 Twitter API 错误处理，避免临时失败把整条流程搞崩
很多 search 和 lookup 流程会在 retry、fallback 和 debug note 都没写清楚时，悄悄变得不可维护。稳的 error handling，会让 monitoring path 更可读，也更容易让团队信任。
1. 先把“可重试失败”和“需要人工看”的失败分开
不是每种失败都该走同一条处理路径。有些应该自动重试，有些则应该留下明确 workflow state 等团队复核。
很多时候，静默失败比显式失败更伤害团队信任。
- 先区分 retryable failure 和 reviewable failure。
- 给 dropped / skipped record 一个明确状态。
- 结果本来应该出现时，不要静默 suppress。
2. retry 最好窄而且可解释
当 retry 规则太宽、又没人说得清为什么这样写时，后面的 debug 会非常难做。
更稳的方式，通常是把 retry 收窄到少数明确的临时失败条件。
- 只重试那些明显偏临时的失败。
- retry 次数和间隔显式写出来。
- 把为什么触发 retry 一起记录下来。
3. 给失败结果留足够上下文
即使 search 或 lookup 失败，也最好留下足够 workflow context，让团队知道当时在跑什么 job、什么 query 或账号参与了这次失败。
这在 repeated monitoring 里尤其重要，因为很多失败只有以后才会看出影响。
- 把 job 或 query identity 和 failure 绑在一起。
- 需要时保留失败账号或 source id。
- 记录失败之后工作流进入了什么状态。
4. 重复失败应该回流到维护工作里
最有用的错误处理，不只是 retry，而是当一类失败反复出现时，能告诉团队这条工作流本身要维护了。
很多 repeated failure 最后都说明 query、checkpoint 或 routing 逻辑需要重看。
- 按 job 跟踪 repeated failure，而不是只按 request。
- 某类失败反复出现时，创建 maintenance review。
- 相似工作流尽量复用同一套 error label。
这条流程跑出第一次结果后，团队接着会问的问题
这些通常会在 Twitter / X 数据流程不再只是一次性测试、而是开始长期跑任务时出现。
最常见的 error-handling 失误是什么？
通常是太早把失败吞掉，而不是把它显式留成团队还能复核的 workflow state。
是不是所有失败都该重试？
通常不该。retry 最稳的做法是只覆盖少数明显临时的失败。
为什么这种问题值得单独展开写？
因为它回答的是团队在“第一次成功请求之后”真正会遇到的维护问题，这类问题比泛产品话术更真实，也更容易建立可信度。
通常会一起看的实现页
如果问题更像“结果不完整”而不是显式失败，可以继续看这页。
如果 repeated failure 其实是 checkpoint 问题，可以继续看这页。
如果 endpoint 选错导致工作流太复杂，可以继续看这页。
如果你想把 error handling 决策和文档里的实现方式对照起来，可以继续看文档。
把 Twitter / X 公开帖子做成团队能反复运行的流程
如果这些问题已经开始频繁出现在你的流程里，可以去验证 tweet search、账号复核或 timeline 接入路径，并把输出接进稳定团队循环。