# 智能体限制与错误 (/docs/developers/agent/limits-and-errors)



本页用于排查智能体配置和会话 API。嵌入令牌、来源、匿名配额与前端组件另见[嵌入限制与错误](/docs/developers/agent/embed/limits-and-errors)；组织余额与配额见[用量与费用](/docs/developers/account/billing)。

## 请求与运行限制 [#limits]

| 项目                    | 值             | 单位与含义                                   |
| --------------------- | ------------- | --------------------------------------- |
| 智能体名称 `name`          | 1–256         | 字符                                      |
| 指令 `system`           | 100,000       | 字符上限                                    |
| 智能体 / 会话 `metadata`   | 16 / 64 / 512 | 键值对 / 键字符数 / 值字符数                       |
| 会话标题 `title`          | 500           | 字符上限                                    |
| 初始输入 `initial_events` | 50            | 事件上限                                    |
| 会话与事件列表 `limit`       | 1–100; 20     | 范围；默认条数                                 |
| 会话预算 `budget`         | 2000          | 默认美分（20 美元）                             |
| 会话时区 `time_zone`      | UTC           | 默认；传入时为 IANA 名称                         |
| 自定义工具                 | 32 / 16 KiB   | 数量上限 / 单个 input\_schema 的 UTF-8 JSON 上限 |

预算对象使用 `type: "limit"`，`max_list_cost.currency: "USD"`，`max_list_cost.amount` 为正整数字符串，单位是美分；`null` 移除预算。它控制后续模型请求，不是费用预测。字符串长度按 JavaScript 字符串长度校验，非所有字符都占一个单位；工具 schema 的大小则按 UTF-8 字节计算。

## 按错误处理 [#errors]

原生 API 的错误体包含 `error.type`、`error.message` 和 `request_id`。服务端已分类的错误还可提供 `error.code` 与 `error.retryable`；请求解析阶段可能只有类型和消息。下列代码以实际响应为准，不能假设每个相同 HTTP 状态都表示同一个原因。

### INVALID\_PARAMS [#invalid-params]

HTTP 400。请求字段、格式或不支持的选项不合法。按错误消息修正请求，原样重试不会解决。

### UNAUTHENTICATED [#unauthenticated]

HTTP 401。凭证缺失或无效。确认当前环境和组织的 Key，重新认证后再请求。

### SESSION\_FORBIDDEN [#session-forbidden]

HTTP 403。当前身份无权访问该会话。核对所属用户与组织，不自动重试，也不要通过换 ID 探测其他用户。

### AGENT\_NOT\_FOUND [#agent-not-found]

HTTP 404。智能体或版本不存在，或对当前身份不可见。使用创建响应中的 ID，并确认版本。

### SESSION\_NOT\_FOUND [#session-not-found]

HTTP 404。会话不存在或不可见。核对返回的会话 ID 与调用身份，不能靠重试创建响应来恢复。

### MODEL\_NOT\_ALLOWED [#model-not-allowed]

HTTP 400。选择的模型不在固定版本允许的模型集合中。使用允许的模型，或更新配置后创建新会话。

### SESSION\_CONFLICT [#session-conflict]

HTTP 409。会话状态与当前操作冲突。重新读取会话或待确认工具，再决定是否提交；不要重复提交已完成的工具结果。

### SESSION\_ARCHIVED [#session-archived]

HTTP 409。会话已归档，不能继续发送消息。保留历史用于查询，新对话创建新会话。

### INVALID\_STATE [#invalid-state]

HTTP 409。当前状态不允许操作，例如删除仍在运行的会话。先中断或等到空闲、终止，再核对状态后操作。

### INVALID\_PAGE\_TOKEN [#invalid-page-token]

HTTP 400。分页游标无效或不匹配当前查询。重新从第一页开始；后续原样传回 next\_page，并保持筛选条件。

### UPSTREAM\_UNAVAILABLE [#upstream-unavailable]

HTTP 502。上游暂时不可用，可在退避后重试。对创建或发消息先查询已有结果，避免重复产生任务。

### SANDBOX\_UNAVAILABLE [#sandbox-unavailable]

HTTP 503。运行环境暂时不可用，可在退避后重试。持续失败时记录请求标识并联系支持。

## 何时重试 [#retry]

`error.retryable: false` 时先处理原因。收到 HTTP 429 时读取 `Retry-After`，不要无间隔循环；临时上游或环境错误可以退避后重试。网络断开不能证明请求未执行，创建资源和发送消息前应先查询已知会话及事件。

事件流已经开始后，运行失败可能通过事件返回，不能只看建立连接时的 HTTP 成功状态。检查回复、工具待确认和会话状态；不要把接收消息成功等同于任务完成。

## 记录诊断信息 [#diagnostics]

保留发生时间、环境、智能体与会话 ID、HTTP 状态、错误类型与代码，以及 `X-Request-Id`；若响应仅提供 `request-id` 或 `request_id`，同时记录该值。不要记录 Key、嵌入令牌或访客凭据。

随后[查看会话与用量](/docs/developers/agent/monitor)，对照 [API 参考](/docs/api/native/agent)检查请求。需要复现时，从[快速开始](/docs/developers/agent/quickstart)的最小请求缩小范围。