错误码说明
code 是稳定的判断依据，msg 的文案会随版本调整。请用 code 做分支处理。
响应结构与 HTTP 状态码的说明见 API 概述。
1xxx · 认证与权限
| code | HTTP | 含义 | 处理方式 |
|---|---|---|---|
| 1001 | 401 | Key 无效、已吊销或已过期 | 检查是否带了 Authorization 头，以及 Key 是否仍有效 |
| 1002 | 403 | Key 缺少本次操作需要的权限 | 看 detail.missing；权限不可修改，需另建一把带该权限的 Key |
| 1003 | 403 | 订阅已过期（仅限制写操作） | 续费后恢复；读取接口不受影响 |
| 1004 | 403 | 使用了系统托管 Key | 到控制台「API Key」页创建自己的 Key |
系统托管 Key 是平台内部自动签发的，不在你的 Key 列表里，无法用于开放 API。
2xxx · 配额与频率
| code | HTTP | 含义 | 处理方式 |
|---|---|---|---|
| 2001 | 429 | 请求过于频繁 | 按 detail.retry_after 等待后重试，通常几秒 |
| 2002 | 429 | 套餐配额用尽（当日检测次数 / 意图词启用上限） | 次日重置，或停用几条意图词，或升级套餐 |
| 2003 | 429 | 距上次监测间隔不足 | 等到 msg 给出的时间点，分钟到小时级 |
| 2004 | 402 | 发布点数不足 | 看 detail 的 quota / used / required，充值或等下个周期 |
⚠️ 2001 / 2002 / 2003 的 HTTP 状态码都是 429，但等待时长差别很大。如果把 2002 当成 2001 来重试，客户端会每隔几秒重试一整天却始终失败。请按
code分别处理。
3xxx · 资源与参数
| code | HTTP | 含义 | 处理方式 |
|---|---|---|---|
| 3001 | 404 | 资源不存在，或不在你的账号下 | 核对 ID 是否正确、是否属于个人空间 |
| 3002 | 400 | 参数不合法 | 看 msg 的说明 |
| 3003 | 409 | 与当前状态冲突（如该品牌已有一轮监测在跑、工单已推送） | 等上一轮结束；已推送的工单无法撤回 |
| 3004 | 400 | 前置条件不满足（没有启用的意图词 / 未匹配到可用平台） | 先补齐前置条件，再重试 |
出于账号数据安全考虑，「资源不存在」和「资源不属于你」统一返回 404，不做区分。
5xxx · 服务端
| code | HTTP | 含义 | 处理方式 |
|---|---|---|---|
| 5000 | 500 | 服务端内部错误 | 带上请求时间联系我们 |
| 5001 | 503 | 检测资源暂时不可用 | 可以稍后重试，这类情况会自行恢复 |
排查步骤
遇到问题建议按这个顺序排查：
- 先调
GET /openapi/v1/me—— 确认 Key 本身可用，并看清它的权限 - 看
code而不是 HTTP 状态码 —— 429 和 403 各有三种不同原因 - 看
detail—— 缺哪个权限、还差多少点数、需要等多久，都在里面 - 监测没结果时先看
platforms[].status——skipped表示该平台本轮不可用，不是参数问题
容易误判的几种情况
| 现象 | 实际原因 |
|---|---|
发起监测返回 status: "queued" 而不是 running | 正常，资源繁忙时先排队，之后会自动开始 |
| 监测结果比选的平台少 | 看 platforms[].status 里的 skipped 与 reason |
刚生成完意图词就发起监测，返回 3004 | 生成的意图词默认停用，需先逐条启用 |
| 媒体列表筛选没生效 | 多值参数要重复传：?areas=a&areas=b，不能写成 ?areas=a,b |
| 提交发稿成功但稿件没出现 | 工单先进入待审核队列，用发稿记录查真实状态 |
| 订阅过期后读取接口仍能用 | 正常，过期只限制写操作 |