错误处理
Scrumball API 的所有错误响应使用同一 JSON 结构：success 为 false，code 为 HTTP 状态码，message 为简短说明。以下逐一说明每个状态码的含义、常见触发原因和修复步骤。
错误响应结构
json
{"success": false,"code": 400,"message": "Bad Request"}
400Bad Request
含义
服务端无法解析或接受该请求，请求在进入业务逻辑前即被拒绝。
常见原因
- 请求体不是合法 JSON（POST 类接口，如 search、monitor 创建任务）。
- Content-Type 未设置为 application/json。
- 查询参数格式错误，例如日期未按要求格式传入。
- 路径拼写错误导致命中了错误的路由。
处理方式
- 核对请求路径与 HTTP method 是否与接口参考页一致。
- POST 接口确认请求头含 Content-Type: application/json。
- 用 JSON 校验工具确认请求体可被正确解析。
- 对照接口页的「Required Parameters」逐项检查参数名与格式。
401Unauthorized
含义
请求缺少有效的 API Key，服务端无法识别调用方身份。
常见原因
- 未传 Authorization 请求头。
- Key 值前误加了 Bearer 前缀（本 API 直接传原始 Key，不需要前缀）。
- Key 已被删除或轮换，本地仍在使用旧值。
- Key 值复制时带入了空格或换行。
处理方式
- 确认请求头格式为 Authorization: YOUR_API_KEY，不带任何前缀。
- 在 Dashboard > API Keys 确认该 Key 仍处于启用状态。
- 如 Key 已失效，创建新 Key 并更新服务端环境变量。
- 先用 GET /api/ping 验证连通性，再排查具体业务接口。
403Forbidden
含义
身份识别通过，但当前账号无权访问该接口或配额已耗尽。
常见原因
- 当前套餐不包含该接口（例如受众画像或实时采集类接口）。
- 试用额度已用完。
- 订阅已过期。
- 该接口对当前账号处于未开放状态。
处理方式
- 在 Dashboard > Usage 查看当前剩余额度。
- 在 Dashboard > Billing 确认订阅状态与套餐包含的接口范围。
- 如需开通更高权限接口，升级套餐或联系支持。
- 区分 403 与 429：403 是无权限，429 是频率超限。
404Not Found
含义
请求路径不存在，或查询的目标资源在数据库中无记录。
常见原因
- 接口路径拼写错误，或使用了已废弃的路径。
- HTTP method 不匹配（例如对 POST 接口发起 GET 请求）。
- 查询的红人账号不在持久化库覆盖范围内。
- 视频 / 帖文已被删除或转为私密。
处理方式
- 对照接口参考页核对完整路径与 method。
- 确认 Base URL 为 https://openapi.scdata.cc，不要指向文档站域名。
- 如为账号查不到，改用对应的 realtime 接口触发实时采集。
- 区分 404 与「返回 200 但 data 为 null」：后者表示路径正确但无数据。
429Too Many Requests
含义
请求频率超出当前套餐允许的上限，服务端主动限流。
常见原因
- 瞬时并发数过高。
- 批量任务未做节流，短时间内发出大量请求。
- 多个服务实例共用同一 Key 且未协调调用频率。
- 重试逻辑未加退避，失败后立即重试形成放大。
处理方式
- 降低并发数，控制单位时间内的请求量。
- 实现指数退避重试：首次等待 1 秒，之后依次翻倍，上限建议 32 秒。
- 批量场景改为队列消费，控制消费速率。
- 在 Dashboard > Usage 查看当前用量曲线，定位峰值时段。
500Server Error
含义
服务端在处理请求时发生未预期的异常，与请求本身无关。
常见原因
- 上游平台数据源临时不可用。
- 服务端内部异常。
- 特定参数组合触发了未覆盖的边界情况。
处理方式
- 加入退避重试，通常短暂等待后可恢复。
- 记录完整请求上下文：请求路径、全部参数、请求时间、响应体。
- 若同一请求持续复现，携带上述上下文联系支持。
- 在客户端将 5xx 与 4xx 区分处理：5xx 可重试，4xx 需修正请求。