# API 错误处理


请求失败时同时查看状态、`errorCode` 和 `errorMessage`。

| 状态或提示 | 先检查 |
| --- | --- |
| 401、Missing API key、Key 无效或过期 | Authorization 格式、完整 Key、状态和有效期 |
| 403、无数据访问或订阅权限 | Key 的数据访问权限、订阅和组织范围 |
| 400、422、参数校验失败 | 参数拼写、limit、模式和筛选组合 |
| 402、insufficient_balance | 当前可用计费资金 |
| 402、entitlement_required | 是否需要另行约定数据访问条件；单纯充值不能解决 |
| 503 | 服务、计价或并发读取暂不可用；保留错误，稍后重试 |

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

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

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

持续失败时向 [hello@humanbased.ai](mailto:hello@humanbased.ai) 提供请求时间、路径、状态码、错误信息和脱敏订阅范围。不要提供完整 Key。

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