背景
我在基于本地部署的 wechat-article-exporter 做公众号文章批量采集时，封装了一个 Python 客户端脚本调用：
GET /api/public/v1/articleGET /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 仍然记录成功，造成归档污染，后面很难批量区分真假正文。
期望
建议下载接口在失败时提供更明确、可机器判断的响应契约，例如：
- 非成功下载时返回非 2xx HTTP 状态码；或
- 保持 2xx 但设置稳定的
Content-Type: application/json，并用统一结构表达错误；或
- Markdown 成功时保证
Content-Type / body 形态可区分，例如明确返回 text/markdown 或类似类型；或
- 在文档里说明
/download 客户端应检查哪些字段/响应特征，不能只依赖 HTTP 状态码。
客户端侧临时规避
我目前在本地脚本里加了保护：写入 .md 前会拒绝空内容、base_resp.ret != 0 的 JSON、以及明显的 HTML/错误页内容。这个可以避免本地归档被污染，但如果上游接口契约更清晰，会更适合第三方脚本、n8n 节点或其他批量自动化客户端集成。
谢谢维护这个工具。
背景
我在基于本地部署的
wechat-article-exporter做公众号文章批量采集时，封装了一个 Python 客户端脚本调用：GET /api/public/v1/articleGET /api/public/v1/download?url=...&format=markdown调试过程中发现一个容易踩坑的接口契约问题：调用方如果只检查 HTTP 状态码，可能会把下载失败时返回的 JSON 错误体、空响应或 HTML 错误页直接写成
.md文件。现象
客户端请求
/api/public/v1/download时，下载失败不一定能被普通的raise_for_status()/ HTTP 2xx 检查捕获。对于自动化批量采集场景，这会导致：.md文件实际内容是base_resp错误 JSON；index.json仍然记录成功，造成归档污染，后面很难批量区分真假正文。期望
建议下载接口在失败时提供更明确、可机器判断的响应契约，例如：
Content-Type: application/json，并用统一结构表达错误；或Content-Type/ body 形态可区分，例如明确返回text/markdown或类似类型；或/download客户端应检查哪些字段/响应特征，不能只依赖 HTTP 状态码。客户端侧临时规避
我目前在本地脚本里加了保护：写入
.md前会拒绝空内容、base_resp.ret != 0的 JSON、以及明显的 HTML/错误页内容。这个可以避免本地归档被污染，但如果上游接口契约更清晰，会更适合第三方脚本、n8n 节点或其他批量自动化客户端集成。谢谢维护这个工具。