ClouisleClouisle

状态与错误参考

查阅资源状态、运行状态和错误码族

Clouisle API 成功和失败都使用统一响应结构：

{"code": 0, "data": {}, "msg": "success"}

分页数据位于 data.items，并包含 total、page、page_size。响应体中的 code 是权威的应用级错误码；HTTP 状态码只是传输层提示，两者并非一一对应。

常见资源状态

资源状态
Agent/工作流draft、published
知识库active、processing、error、archived
文档pending、processing、completed、error
工作流运行pending、running、waiting、success、failed、cancelled、timeout
节点执行pending、running、waiting、success、failed、skipped
暂停请求pending、submitted、cancelled
API Keyactive、inactive、expired（由 is_active 与 expires_at 派生）

waiting 与 cancelled/timeout 的归属

waiting 表示运行或节点停在 pause 节点、等待外部提交变量或审批（RunStatus.WAITING / NodeStatus.WAITING）。cancelled 与 timeout 只出现在运行级状态；节点级状态不含这两个值，而是包含 skipped（被条件或分支跳过）。

错误码族

范围含义
0成功
1000-1999通用错误：未知错误、校验失败、请求错误、内部错误
2000-2999认证、Token 和账户状态
3000-3999权限、团队成员和管理员要求（如 3002 非团队成员、3003 需团队管理员）
4000-4999用户、角色、团队等资源不存在
5000-5099注册与邮箱验证
5100-5199资源已存在（重复）
5200-5299操作被禁止（系统角色/权限保护、所有权保护、状态冲突）
5300-5399登录安全：账户锁定、验证码、密码策略
5310-5319TOTP 两步验证
5400-5499限速与配额映射
6000-6099知识库、文档和分块
6100-6199模型、授权、配额和能力
6200-6299Agent、会话和消息
6300-6399SSO 配置、认证和会话

HTTP 状态与业务码的映射

场景HTTP 状态业务码
业务错误（BusinessError 默认）400其自身 code（如 5002 用户名已存在）
请求体校验失败（Pydantic）4221001（VALIDATION_ERROR）
JWT 认证失败4032003（INVALID_CREDENTIALS）
API Key 无效 / 过期4012001（INVALID_TOKEN）/ 2002（TOKEN_EXPIRED）
未提供认证4012000（UNAUTHORIZED）
权限不足4033000（PERMISSION_DENIED）/ 3001（INSUFFICIENT_PRIVILEGES）

许多 BusinessError 会带显式 status_code（404 资源不存在、403 权限、401 认证等），因此客户端应以响应体里的 code 为准，而不是只看 HTTP 状态。

恢复原则

  • 401 / 2000-2002：刷新登录或替换 API Key（API Key 过期需重新创建）。
  • 403 / 3000-3003：检查全局角色权限、团队归属与资源范围；3003 表示需要团队 owner/admin。
  • 404 / 4000-4999、6000-6002：确认 ID 与资源状态。
  • 5400：邮件配额或上游供应商限速，按对应窗口退避后重试。
  • 6103 / 6104：模型团队配额超限 / 模型未被授权，检查团队模型授权与用量。
  • 文档处理失败（6004）或工作流运行失败：先查看资源级错误详情，修复配置后重新处理或重新运行。
API 错误响应
API 错误响应

这篇文章对你有帮助吗？

本页目录

常见资源状态错误码族HTTP 状态与业务码的映射恢复原则