智能体限制与错误

本页用于排查智能体配置和会话 API。嵌入令牌、来源、匿名配额与前端组件另见嵌入限制与错误；组织余额与配额见用量与费用。

请求与运行限制

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

按错误处理

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

INVALID_PARAMS

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

UNAUTHENTICATED

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

SESSION_FORBIDDEN

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

AGENT_NOT_FOUND

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

SESSION_NOT_FOUND

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

MODEL_NOT_ALLOWED

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

SESSION_CONFLICT

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

SESSION_ARCHIVED

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

INVALID_STATE

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

INVALID_PAGE_TOKEN

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

UPSTREAM_UNAVAILABLE

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

SANDBOX_UNAVAILABLE

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

何时重试

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

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

记录诊断信息

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

随后查看会话与用量，对照 API 参考检查请求。需要复现时，从快速开始的最小请求缩小范围。