上线检查清单

从脚本走向生产前，按下面的清单逐项核对。每一项都链接到详细说明。

安全

• API Key 只存放在服务端的环境变量或密钥管理服务中，没有出现在前端代码、App、代码仓库和日志里。见认证与 API Key。
• 生产、测试使用不同的 Key，并为非长期用途的 Key 设置了有效期。
• 团队知道 Key 泄露时怎么处理：在控制台重置并选择「立即失效」，或停用。见管理 API Key。
• 有 Key 轮换流程：重置时给旧 Key 留出宽限期，新 Key 部署完成后再让旧 Key 失效。

异步任务与可靠性

• 提交后立即持久化 task_id，并在自己的系统里记录提交时间和参数。
• 轮询间隔约 15 秒；未结束的任务由定时循环批量查询，不为每个任务单独阻塞等待。见任务生命周期。
• 业务超时不等于失败：超时后保留 task_id，之后仍能取回结果。
• 判断任务成败只看 status，不因 error_code 非空就判失败。
• 提交请求超时、断连或返回 -1 时，先用任务列表确认是否已创建，不盲目重复提交。见错误处理。
• 使用 wait_seconds 时，客户端 HTTP 超时大于 wait_seconds，并能处理返回非终态的情况。

请求与错误处理

• 用响应体的 ret 判断请求成败，而不是 HTTP 状态码；同时处理非 200 状态码和网络错误。
• 解析 msg（JSON 字符串）得到可展示的提示，解析失败时回退为原文。
• 请求体只包含接口定义的字段，字段名使用下划线风格（task_id、wait_seconds）。
• 解析响应时忽略不认识的字段，以兼容今后新增的字段。
• -1、1024、1025 做了退避重试；1001、1003、1022、1023、1029、1030、1031 不自动重试，而是告警或提示。
• 遇到未知的 error_code 按「任务失败、不扣费」处理，并记录 error_message。

限流与成本

• 批量提交时在客户端节流，低于每分钟提交上限；遇到 1024 / 1025 会退避。见限流与配额。
• 平台列表从接口动态获取，不写死；maintenance 状态的平台不提交。
• 按场景选择优先级：批量、定时任务用 P2，时效敏感的用 P1。见平台、优先级与国家。
• 余额低于预警线时有告警（控制台「用量统计」可查看余额与到期时间），避免任务因 1023 中断。见计费与点数。

结果解析

• 读取 raw_result 前判断它是否存在；对省略的零值字段补默认值。
• elapsedMs 按字符串解析为数字。
• cited 按三态处理，字段不存在不当作 false。见解析回答结果。
• 使用思考模式时，以 raw_result.thinking 判断实际是否开启，不以提交的 thinking 为准。见思考模式。
• 使用 url 前校验是否为 http(s) 链接。
• 需要长期保存的图片已自行转存（imageUrl 会过期）。
• 展示给用户前按需清洗正文里的平台引用标记。

可观测性

• 记录每次请求的接口、ret、耗时、task_id，以及响应头 ipalfish-trace-id（如有），便于排查。
• 监控任务失败率与 error_code 分布，按平台拆分；某个平台持续 crawl_failed 时考虑暂时换平台。
• 定期与控制台「调用日志」「用量统计」对账。

相关页面

API 概述请求与响应的通用约定。

常见问题接入过程中的高频疑问。