# 数据读取 API 错误处理


调用 `GET /v1/live/pull` 时，同时查看 HTTP 状态、`success`、`errorCode` 和 `errorMessage`。保存收到的原响应；完全没有响应时，单独按下方的读取模式处理。[Campaign API 写入](/zh/api/campaign-api)使用不同的请求和回执规则。

| 状态或提示 | 后续动作 |
| --- | --- |
| 401、Missing API key、Key 无效或过期 | 核对 `Authorization: Bearer ...` 格式与 Key 状态、有效期；由有权限的人员修正或替换凭证 |
| 403、无数据访问或订阅权限 | 核对 Key 的 Data 权限、选择范围和所属组织；请组织管理员修正授权 |
| 404、Subscription not found | 在 **API Keys → Pull from（读取来源）** 核对 Subscription ID 和 Key 所属组织。其他组织的订阅也可能返回未找到，请管理员核对授权 |
| 400、422、参数校验失败 | 按提示修正字段、limit、模式或筛选组合，再发起限定范围的请求 |
| 402、insufficient_balance | 核对组织可用计费资金，再决定是否重试 |
| 402、entitlement_required | 该数据按申请定价，目前不能自助购买，充值也无法解决；把响应中的 `dataset_id` 发给 hello@humanbased.ai |
| 429、Too many requests | 等待 `Retry-After` 给出的秒数，再降低频率继续，见[调用频率限制](/zh/api/api-fields#rate-limits) |
| 503 | 保留错误和请求范围，待服务恢复后按原定模式重试；持续发生时联系支持 |

未带 Key 的拒绝访问响应示例：

```json
{"data": null, "success": false, "errorCode": 401, "errorMessage": "Missing API key"}
```

`success=true` 但 `items` 为空时，先核对交付、订阅范围、模式和筛选，不按认证失败处理。增量为空可能只是没有新的可交付记录。

## 完全没有收到响应时

先确认使用的读取模式。带 `from=beginning` 的从头读取可在任务允许时重试相同的限定请求和游标，并只保留完整响应；它不会推进订阅共享的增量位置。默认增量请求即使丢失响应，也可能已推进该订阅的共享位置并产生费用。再次增量读取未必返回同一页；先按[已取得范围重读](/zh/api/api-fields)，与本地保存的记录 ID 核对，再决定是否继续增量读取。保留请求时间、Subscription ID、筛选条件和最近保存的记录 ID 供支持定位。

持续失败时向 [hello@humanbased.ai](mailto:hello@humanbased.ai) 提供环境、请求时间、路径、收到的状态码、脱敏错误、读取模式和订阅范围。发送前删去完整 Key。

相关说明：[凭证与权限](/zh/api/api-auth) · [读取方式](/zh/api/api-data) · [组织资金](/zh/collaboration/billing)。