错误与排错

文档解析的失败通常来源于三类问题：输入文件不可访问、文档类型/结构复杂、以及调用参数与资源限制。

常见问题清单

1) 访问失败或权限问题

• URL 需要登录才能下载
• 站点对爬虫/机器人做了限制
• 链接临时失效或返回 4xx/5xx

处理建议：先在浏览器确认 URL 可直接下载；必要时更换可公开访问的源，或走你自己的代理下载后再处理。

1.5) Cache-only 查询导致 404

当你设置 minAge 时，系统只查缓存且不会触发新抓取。若缓存不存在，会返回 404，错误码为 SCRAPE_NO_CACHED_DATA。

2) 输出为空或缺失正文

常见于扫描 PDF 或图像密集页：

• 先尝试把 PDF 模式切到 ocr
• 或对前 5–10 页抽样验证，再扩大 maxPages

参考：扫描 PDF 与 OCR

3) 表格错行/列错位

• 先判断是文本表格还是扫描表格
• 对表格密集文档建立单独策略，并保留回归样本持续迭代

参考：表格与公式

4) 402 / 429 / 500

• 402：通常表示 credits 不足或计费相关问题
• 429：触发限流（可以降低并发、增大超时或改用队列/批处理）
• 500：服务端错误或站点异常，建议缩小 maxPages 抽样复现，再调整策略

推荐的排错流程

1. 先用小页数抽样：maxPages: 5
2. 判断文档类型：文本 PDF vs 扫描 PDF
3. 决定模式：fast / auto / ocr
4. 固化为策略：把“文档特征 → 参数组合”记录下来，形成可复用规则