API 错误与重试

所有响应都使用同一信封结构，成功与失败共用：

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

失败时 code 为非零，data 可能为 null 或携带结构化细节（如超出的大小上限、剩余尝试次数）。msg 已按请求语言本地化，不要用 msg 文本分支，请始终用 code。

HTTP 状态映射

HTTP 状态与业务 code 并非一一对应。同一个 code 可能以不同 HTTP 状态出现（例如 2003 在 JWT 解析失败时为 403，在密码错误时为 400），因此先看 HTTP 状态做粗分类，再以响应体中的 code 做精确分支。

业务错误码清单

下表覆盖当前版本全部已定义错误码。某一区间未使用的号码属于保留段，请勿实现分支。

HTTP 列标注的是当前代码实际抛出的状态；标「400」表示未显式指定状态（BusinessError 默认值）。少数 code 在不同端点会使用不同状态（例如 1004、3001、6000 系列、6100），表中给出最常见取值，实际仍以响应为准。

通用错误（1000-1999）

1001 的 data.errors 是字段名到消息数组的字典，不是数组：

{
  "code": 1001,
  "data": {
    "errors": {
      "email": ["Invalid email address"],
      "password": ["String should have at least 8 characters"]
    }
  },
  "msg": "Validation error"
}

认证错误（2000-2999）

2001 还用于单会话模式下被新登录顶下线的旧令牌（msg_key 为 session_expired_new_login），以及令牌黑名单命中。

权限错误（3000-3999）

3000 也是 API Key 资源绑定不匹配的返回码（msg_key 为 api_key_no_agent_access / api_key_no_workflow_access），见 API Keys API。

资源错误（4000-4999）

注册与账户（5000-5099）

该区间统一返回 HTTP 400。5007 的 data、5008 的 data.remaining_seconds 可提供更精确的提示。

重复冲突（5100-5199）

该区间统一返回 HTTP 400。重试不会成功，请改名或改为更新既有资源。

操作被禁止（5200-5299）

该区间统一返回 HTTP 400。变更为 owner 请使用移交所有权接口，见 Teams API。

登录安全（5300-5399）

速率限制（5400-5499）

5400 的 data 会给出具体维度，例如批量发信时的 {"limit": 100, "period": "hour"} 或 {"requested": 3, "remaining": 1}。

知识库（6000-6099）

6007 与 6201（Agent）语义一致：资源存在但当前用户/API Key 不在可访问范围内。客户端应提示申请权限，而不是重试。

模型（6100-6199）

6103 唯一稳定返回 HTTP 429；6106 与 6104 都表示「当前不可用」，但 6104 需要在团队模型授权中新增记录，6106 只需重新启用已有授权的 is_enabled。

Agent 与会话（6200-6299）

SSO（6300-6399）

该区间统一返回 HTTP 400（6306 出现在登录接口，因此也提示「改用 SSO 登录」而不是重试）。

处理表

可重试与不可重试

网络超时、503/504、供应商暂不可用、5400 与 6103 限速，以及部分后台任务失败可以指数退避重试。

以下情况不要盲目重试：

• 1001-1004：请求本身非法，重试会得到同样结果。
• 3000-3004、6007、6201：权限问题，需先变更授权。
• 2001、2002、2004：凭据或账号状态问题。
• 4000-4005：资源不存在，先确认 ID 与上下文。
• 5100-5214：约束冲突，需改变请求内容。
• 6104、6106：模型授权或启用状态问题。
• 6306：该部署已关闭密码登录。

SSE 错误处理

流式端点在线路中途出错时不会改变 HTTP 状态（此时响应头已发出），而是在事件流中推送错误事件：

• Agent 流收到 error 事件后，保留已接收的正文与 message_id，再决定重试或提示用户。因为此时消息可能已落库，重试前先查询会话消息，避免重复提问。
• 工作流流断线后使用 stream_url 与最后收到的事件序号恢复订阅，不要重新触发 POST /workflows/{workflow_id}/run。

两类流的完整事件清单见 流式事件。

相关文档

• 认证与用户登录 API：2000-2004、5300-5316、6306 的产生场景
• API Keys API：2001、2002、3000 与 API Key 绑定限制
• Teams API：3002-3004、4004、4005、5102、5103 与 5206-5210
• Users API：5002、5003、5212-5214 与密码生命周期错误