下载接口失败时建议返回明确错误状态，避免客户端误写成 Markdown

背景

我在基于本地部署的 wechat-article-exporter 做公众号文章批量采集时，封装了一个 Python 客户端脚本调用：

• GET /api/public/v1/article
• GET /api/public/v1/download?url=...&format=markdown

调试过程中发现一个容易踩坑的接口契约问题：调用方如果只检查 HTTP 状态码，可能会把下载失败时返回的 JSON 错误体、空响应或 HTML 错误页直接写成 .md 文件。

现象

客户端请求 /api/public/v1/download 时，下载失败不一定能被普通的 raise_for_status() / HTTP 2xx 检查捕获。对于自动化批量采集场景，这会导致：

• 本地生成的 .md 文件实际内容是 base_resp 错误 JSON；
• 或者是微信/页面错误 HTML；
• 或者是空正文；
• 后续 index.json 仍然记录成功，造成归档污染，后面很难批量区分真假正文。

期望

建议下载接口在失败时提供更明确、可机器判断的响应契约，例如：

1. 非成功下载时返回非 2xx HTTP 状态码；或
2. 保持 2xx 但设置稳定的 Content-Type: application/json，并用统一结构表达错误；或
3. Markdown 成功时保证 Content-Type / body 形态可区分，例如明确返回 text/markdown 或类似类型；或
4. 在文档里说明 /download 客户端应检查哪些字段/响应特征，不能只依赖 HTTP 状态码。

客户端侧临时规避

我目前在本地脚本里加了保护：写入 .md 前会拒绝空内容、base_resp.ret != 0 的 JSON、以及明显的 HTML/错误页内容。这个可以避免本地归档被污染，但如果上游接口契约更清晰，会更适合第三方脚本、n8n 节点或其他批量自动化客户端集成。

谢谢维护这个工具。