> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acturehub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误处理

> BP-Agent 通用错误结构、错误码与重试原则。

成功响应通常包含：

```json theme={null}
{
  "code": 0,
  "message": "操作成功",
  "data": {}
}
```

错误响应通常包含：

```json theme={null}
{
  "code": 1000,
  "message": "错误说明",
  "detail": {},
  "timestamp": null
}
```

## 通用错误码

|   code | 含义     | 建议行为             |
| -----: | ------ | ---------------- |
| `1000` | 请求错误   | 修正请求参数           |
| `1001` | 未认证    | 检查 Token 和环境     |
| `1002` | 无权限    | 检查租户及资源归属        |
| `1003` | 资源不存在  | 检查 ID 与环境        |
| `1004` | 参数校验失败 | 根据 `detail` 修正字段 |
| `1005` | 业务冲突   | 根据业务提示处理幂等或状态冲突  |
| `1006` | 请求过于频繁 | 退避后重试            |
| `1007` | 配额不足   | 联系管理员或等待配额恢复     |
| `5000` | 服务内部错误 | 保留请求信息并联系支持      |
| `5002` | 外部依赖异常 | 根据返回信息决定是否重试     |
| `5003` | 文件处理错误 | 检查 PDF 后重新上传     |

## 重试原则

* 参数、鉴权、文件格式和配额问题在修正前不要重试。
* `detail.retryable=true` 时才按退避策略自动重试。
* 创建任务请求超时后，先查询现有任务，不要直接重复创建。
* 向支持人员提供时间、环境、请求路径、业务 ID 与响应错误，不要提供完整 Token。