错误码

所有错误响应结构一致。

错误响应结构

{
  "request_id": "req-xxxxxxxx",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Agent 'agent-001' not found in workspace 'ws-001'.",
    "details": {
      "agent_id": "agent-001",
      "workspace_id": "ws-001"
    }
  }
}

HTTP 状态码

状态	含义	客户端应该
`200`	成功	用响应数据
`201`	已创建	用响应中的资源 ID
`204`	成功无内容	不要解析 body
`400`	参数错	改请求,不要重试
`401`	未认证	检查 Token,不要重试
`403`	无权限	检查 ACL,不要重试
`404`	资源不存在	改请求,不要重试
`409`	冲突（如重复创建)	视情况（冲突可重试)
`422`	业务校验失败	改请求
`429`	速率超限	退避重试（详见速率限制)
`500`	服务器内部错	退避重试
`502 / 503 / 504`	网关 / 服务不可用	退避重试

业务错误码

code	含义
`INVALID_REQUEST`	参数格式错
`RESOURCE_NOT_FOUND`	资源不存在
`FORBIDDEN`	ACL 拒绝
`UNAUTHORIZED`	Token 无效
`RATE_LIMITED`	速率超限
`QUOTA_EXCEEDED`	积分 / 容量超限
`MODEL_UNAVAILABLE`	模型暂时不可用（已 Failover 仍失败)
`TOOL_INVOCATION_FAILED`	工具调用失败
`KB_INDEX_NOT_READY`	知识库索引尚未就绪
`INTERNAL_ERROR`	服务器内部错

重试策略

错误	重试	退避
`400 / 401 / 403 / 404 / 422`	不要	—
`409`	视情况	立即一次，不行就放弃
`429`	✓	看 `Retry-After` 头
`500 / 502 / 503 / 504`	✓	指数退避（1s → 2s → 4s → 8s,最多 5 次)

故障定位：request_id

每个响应都带 request_id。报告问题时带上 request_id,运维可以在毫秒级找到完整链路。

错误响应结构

HTTP 状态码

业务错误码

重试策略

故障定位：request_id

接下来

页面导航