错误处理

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

成功响应通常包含：

{
  "code": 0,
  "message": "操作成功",
  "data": {}
}

错误响应通常包含：

{
  "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。