# 嵌入的限制与错误 (/docs/cloud/services/agent/embed/limits-and-errors) 本页列出嵌入时会碰到的上限和错误码。标注「策略」的值由你为智能体配置的嵌入策略决定，其余是平台固定值。 ## 上限 [#上限] ### 签发令牌 [#签发令牌] | 项目 | 限制 | | ------------------- | ------------------------------------------------------------------------- | | 令牌有效期 `ttl_seconds` | 60 到 3600 秒。不传时用策略的默认值，且不能超过策略的有效期上限（`ttl_max_seconds`，同样在 60 到 3600 之间）。 | | `external_user_id` | 1 到 128 个字符，只能包含字母、数字和 `_ . : @ -`。 | | `system_message` | 文本块总计不超过 8192 字节（UTF-8）。 | | `metadata` | 最多 16 个键；键 1 到 64 个字符，值为不超过 512 个字符的字符串。 | | 会话预算 `budget_cents` | 0 到策略的会话预算上限；不传时用策略的默认值。 | | `allowed_origins` | 必须是策略 `allowed_origins` 的子集。 | ### 策略 [#策略] | 项目 | 限制 | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | 来源白名单 `allowed_origins` | 最多 50 条。只接受 `https` 来源；通配写法 `https://*.example.com` 只匹配一级子域名，不含端口。开启 `allow_localhost` 后额外允许 `http://localhost` 和 `http://127.0.0.1`。 | | 每个终端用户的活跃会话数 `max_active_sessions_per_user` | 1 到 100。只计运行中的会话，不计空闲的历史会话。 | | 每个终端用户每分钟请求数 `per_user_rate_per_min` | 1 到 600。 | | 被封禁的终端用户 `blocked_end_users` | 最多 1000 个。 | | 月度上限 `monthly_cap_cents` | 以分计；`null` 表示不设上限。 | | 触顶动作 `on_cap` | `stop_new_sessions`：拒绝新建会话，返回 `EMBED_MONTHLY_CAP_REACHED`；`alert_only`：只告警，不拦截。 | 月度花费按 UTC 自然月统计。 ### 会话与消息 [#会话与消息] | 项目 | 限制 | | -------------------------- | ------------------------------------------------------------------------------ | | 附件 | 每条消息最多 5 个，单个不超过 10 MB。只支持内联：PNG、JPEG、GIF、WebP 作为图片，PDF、TXT、MD 作为文档，不会上传为会话文件。 | | 推荐问题 `startScreen.prompts` | 最多显示 4 个。 | | 会话标题 | 不超过 500 个字符。 | | 创建会话时的初始事件 | 最多 50 条，只能是纯文本的用户消息。 | | 会话预算 | 达到令牌上的 `budget_cents` 后，会话不再接受新的工作，只接受工具确认和中断。 | ## 错误 [#错误] 错误从两处到达页面：接口返回的错误体，以及 Kit 自身产生的错误。传输错误通过 `praxis.error` 事件的 `detail` 交给你，字段为 `code`、`status`、`retryable` 和 `message`；会话加载或发送失败可能只有 `message`，按错误码分支前先检查 `code` 是否存在。 ### EMBED\_\* 错误码 [#embed_-错误码] | 错误码 | HTTP | 含义 | 可重试 | 建议处理 | | --------------------------- | ---- | --------------------------------------------------------- | --- | --------------------------------------------------------------------------------------------- | | `EMBED_TOKEN_EXPIRED` | 401 | 令牌已过期。 | 否 | Kit 会自动调用 `getToken` 换新令牌并重试一次；持续出现说明你的令牌服务返回了已过期的令牌。 | | `EMBED_TOKEN_REVOKED` | 401 | 令牌已被吊销。 | 否 | Kit 不再刷新，对话进入终止状态。让用户重新进入页面，由你的服务重新签发。 | | `EMBED_ORIGIN_NOT_ALLOWED` | 403 | 页面来源不在白名单内。 | 否 | 把页面来源加入策略的 `allowed_origins`，并确认签发令牌时的 `allowed_origins` 包含它。 | | `EMBED_USER_BLOCKED` | 403 | 该终端用户被封禁。 | 否 | 在策略的 `blocked_end_users` 中确认并移除，或提示用户联系你。 | | `EMBED_RATE_LIMITED` | 429 | 每分钟请求数或同时运行的会话数超限，或达到匿名每日会话上限。 | 是 | 请求限流时稍后重试；并发超限时等待运行结束或中断运行，或调高 `max_active_sessions_per_user`。归档空闲历史不会释放运行名额；每日上限在下个 UTC 日恢复。 | | `EMBED_BUDGET_EXHAUSTED` | 402 | 会话预算耗尽，或达到匿名每日花费上限。 | 否 | 会话预算耗尽时开始新会话，或调高签发时的 `budget_cents`；匿名每日上限需等待额度恢复。 | | `EMBED_MONTHLY_CAP_REACHED` | 402 | 月度上限已到，且触顶动作为 `stop_new_sessions`。 | 否 | 调高 `monthly_cap_cents`，或把 `on_cap` 改为 `alert_only`；下个 UTC 月自动恢复。 | | `EMBED_FIELD_NOT_ALLOWED` | 400 | 创建会话时带了嵌入令牌不允许的字段，或初始事件格式不被允许；也用于策略不允许的 `agent_override`。 | 否 | 只传标题、时区和纯文本的初始用户消息。 | ### 相关的通用错误码 [#相关的通用错误码] | 错误码 | HTTP | 含义 | 可重试 | | ---------------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------- | --- | | `INVALID_PARAMS` | 400 | 请求参数不合法，信息会指出是哪个字段，例如 `Invalid external_user_id`、`system_message exceeds 8192 bytes`。 | 否 | | `NOT_FOUND` | 404 | 授权、策略或请求的资源不存在或不可访问；Hosted 凭证无效、过期或已使用也返回此码。 | 否 | | `UNAUTHENTICATED` | 401 | 凭证缺失或无效，包括已停用的可公开 key。 | 否 | | `AGENT_NOT_FOUND` / `SESSION_NOT_FOUND` | 404 | 找不到智能体或会话。 | 否 | | `SESSION_FORBIDDEN` / `PERMISSION_DENIED` / `READ_ONLY` | 403 | 调用方无权执行此操作；终端用户的资源隔离也可能以 404 隐藏资源。 | 否 | | `INVALID_STATE` / `SESSION_CONFLICT` / `AGENT_ARCHIVED` / `SESSION_ARCHIVED` | 409 | 智能体或会话当前状态不允许此操作。 | 否 | | `INVALID_PAGE_TOKEN` | 400 | 分页或事件游标无效。 | 否 | | `EVENT_CONTENT_UNAVAILABLE` | 404 | 事件内容不可用。 | 否 | | `EVENT_CONTENT_CORRUPT` | 500 | 存储的事件内容无法正确读取。 | 否 | | `UPSTREAM_UNAVAILABLE` | 502 | 上游服务不可用。 | 是 | | `INTERNAL` | 500 | 未分类的服务端错误。 | 否 | ### Kit 自身产生的错误码 [#kit-自身产生的错误码] 这些错误没有对应的接口响应，`status` 为 0 或接口状态码。 | 错误码 | 含义 | 可重试 | | ------------------------ | ------------------------------------- | ---- | | `network_error` | 网络请求失败。 | 是 | | `http_error` | 响应不是已知的错误体。`status` 为 429 或 5xx 时可重试。 | 视状态码 | | `invalid_token` | `getToken` 返回了空令牌。 | 是 | | `invalid_response` | 响应不是合法 JSON，或历史分页没有前进。 | 否 | | `invalid_stream` | 事件流不是 SSE，或某条数据不是合法 JSON。 | 否 | | `stream_disconnected` | 事件流在没有取消的情况下中断。Kit 最多重连 5 次。 | 是 | | `event_cursor_not_found` | 历史中找不到续传位置。 | 否 | | `callback_error` | 事件回调抛出了异常。 | 否 | | `aborted` / `disposed` | 操作被取消，或元素已移除。 | 否 | `getToken` 失败时，Kit 按 1、2、4 秒的间隔最多重试 3 次，之后令牌状态变为过期并发出 `praxis.error`。 ## 暂不支持 [#暂不支持] 以下能力在嵌入里尚未提供： * 按消息切换模型 * 工具模式 * 语音输入 * entities、commands、widgets * 按终端用户的记忆