# 嵌入限制与错误 (/docs/developers/agent/embed/limits-and-errors)



本页适用于嵌入令牌、Kit、iframe 与 Hosted。表中的「来源」区分固定校验、控制台策略和组件行为；策略值以该智能体保存的配置为准。

## 限制 [#limits]

| 项目                             | 值与单位                                                              | 来源                      |
| ------------------------------ | ----------------------------------------------------------------- | ----------------------- |
| `external_user_id`             | 1–128 字符；仅英文字母、数字及 `_ . : @ -`                                    | 签发校验                    |
| `ttl_seconds`                  | 60–3600 秒，同时不超过策略 `ttl_max_seconds`；省略用策略默认值                      | 签发校验与策略                 |
| `system_message`               | 所有 text 块文本合计 ≤8192 UTF-8 字节                                      | 签发校验                    |
| `metadata`                     | ≤16 个键；键 1–64 字符，字符串值 ≤512 字符                                     | 签发校验                    |
| `budget_cents`                 | 0 至策略会话预算上限，单位美分；省略用策略默认值                                         | 签发校验与策略                 |
| 签发 `allowed_origins`           | 只能取策略来源条目的子集，逐项精确匹配                                               | 签发校验                    |
| 策略来源                           | ≤50 条 HTTPS 来源；通配只匹配一级子域且不含端口                                     | 嵌入策略                    |
| `allow_localhost`              | 默认 false；开启后允许 HTTP localhost / 127.0.0.1（可带端口）                   | 嵌入策略                    |
| `max_active_sessions_per_user` | 1–100 个活跃会话/用户；空闲历史不计入                                            | 嵌入策略                    |
| `per_user_rate_per_min`        | 1–600 次/分钟/用户                                                     | 嵌入策略                    |
| `blocked_end_users`            | ≤1000 个用户 ID                                                      | 嵌入策略                    |
| `monthly_cap_cents`            | 非负整数美分；null 不限；按 UTC 自然月                                          | 嵌入策略与月度统计               |
| 页面上下文                          | ≤32 项，完整 JSON ≤4096 UTF-8 字节                                      | 接口校验；Kit 超出时裁剪最早项       |
| 会话标题 / 初始事件                    | 标题 ≤500 字符；初始事件 ≤50 条纯文本用户消息                                      | 嵌入会话创建校验                |
| 附件选择器                          | 每条消息最多 5 个；每个 ≤10 MiB（10,485,760 字节）；PNG、JPEG、GIF、WebP、PDF、TXT、MD | Kit 输入校验；新会话首条消息仍只接受纯文本 |
| `startScreen.prompts`          | 显示前 4 个                                                           | Kit 组件                  |
| Hosted 兑换凭证                    | 60 秒内使用，仅能兑换 1 次                                                  | Hosted 兑换校验             |

月度触顶动作 `stop_new_sessions` 拒绝新会话，`alert_only` 不拦截。控制台金额输入为美元，API 的预算字段为美分。会话预算耗尽后不能继续提交新的工作；保留工具确认和中断入口。

## 服务端错误 [#server-errors]

下列状态用于普通 HTTP 失败响应。事件流已经建立后，错误通过流内事件到达，不能再更改已发送的 HTTP 状态。「可重试」指原请求；修复配置或换取合法凭证后属于新的尝试。

### EMBED\_TOKEN\_EXPIRED [#embed-token-expired]

**401 · 访问阶段 · 不可直接重试。** 令牌到期。可刷新 Kit 会重新取令牌，并对到期响应最多重放一次请求；Hosted 不刷新，须从宿主获取新链接。

### EMBED\_TOKEN\_REVOKED [#embed-token-revoked]

**401 · 访问/事件流 · 不可重试。** 令牌已撤销，Kit 停止刷新。结束旧访问，由宿主重新核验是否仍允许该用户进入；不要自动重签绕过撤销。

### EMBED\_ORIGIN\_NOT\_ALLOWED [#embed-origin-not-allowed]

**403 · 来源检查 · 不可重试。** 当前来源不被允许。核对实际 scheme、host、port，以及策略和签发时收紧的来源列表；修改后重新签发再验证。

### EMBED\_USER\_BLOCKED [#embed-user-blocked]

**403 · 签发/新建会话 · 不可重试。** 用户已封禁。由管理者在「运营与管理 → 终端用户」核查；确需恢复时解封并签发新令牌。

### EMBED\_RATE\_LIMITED [#embed-rate-limited]

**429 · 请求/新建会话/匿名签发 · 可延后重试。** 请求频率、活跃会话数或匿名每日会话额度触顶。分别等待限流窗口恢复、运行结束或下个 UTC 日；不能统一立即重试。

### EMBED\_BUDGET\_EXHAUSTED [#embed-budget-exhausted]

**402 · 会话工作/匿名签发 · 不可重试。** 会话预算或匿名每日花费用尽。由管理者核对预算；获准后以新令牌、新会话继续，或等待每日额度恢复，不循环重签规避上限。

### EMBED\_MONTHLY\_CAP\_REACHED [#embed-monthly-cap-reached]

**402 · 新建会话 · 不可重试。** 月度上限已到且策略要求停止新会话。由管理者决定是否调整上限或触顶动作，或等到下个 UTC 月。

### EMBED\_FIELD\_NOT\_ALLOWED [#embed-field-not-allowed]

**400 · 签发/新建会话 · 不可重试。** 使用了不允许的字段或初始事件。移除未获准的 `agent_override`；嵌入会话创建仅传 `title`、`time_zone`、`initial_events`，初始事件为纯文本 `user.message`（可带页面上下文）。

### 其他拒绝 [#other-errors]

| 码                      | HTTP / 阶段           | 恢复动作                                | 可重试 |
| ---------------------- | ------------------- | ----------------------------------- | --- |
| `INVALID_PARAMS`       | 400 / 参数校验          | 按字段提示修正类型、范围或大小                     | 否   |
| `UNAUTHENTICATED`      | 401 / 鉴权            | 检查凭证是否缺失、失效；公开 key 是否停用             | 否   |
| `NOT_FOUND`            | 404 / 资源或 Hosted 兑换 | 核对组织、公开 ID、策略；失效或已用的 Hosted 链接需重新签发 | 否   |
| `UPSTREAM_UNAVAILABLE` | 502 / 上游调用          | 延后重试；管理写操作先核对是否部分完成                 | 是   |

会话权限、归档和事件内容错误见[智能体限制与错误](/docs/developers/agent/limits-and-errors)。

## Kit 错误与重试 [#kit-errors]

`praxis.error` 的 detail 可能是含 `code`、`status`、`retryable`、`message` 的 `KitError`，也可能只有 `{ message }`。`status: 0` 表示没有 HTTP 响应。

| 码                                     | 状态 / 阶段         | 恢复动作与可重试性                          |
| ------------------------------------- | --------------- | ---------------------------------- |
| `network_error`、`stream_disconnected` | 0 / 网络或事件流      | 恢复连接后可重试                           |
| `http_error`                          | 响应状态 / HTTP     | 检查原始响应；无明确 retryable 时 429、5xx 可重试 |
| `invalid_token`                       | 0 / 取令牌         | getToken 返回空值；修复返回值，可重试            |
| `invalid_response`                    | 响应状态 / JSON 或历史 | 检查返回格式、分页是否前进；不可自动重试               |
| `invalid_stream`                      | 响应状态 / 事件流      | 检查 SSE 内容与 JSON；不可自动重试             |
| `event_cursor_not_found`              | 200 / 历史恢复      | 重新加载历史定位会话；不可自动重试                  |
| `callback_error`                      | 0 / 回调          | 修复宿主异常；不可重试                        |
| `aborted`、`disposed`                  | 0 / 生命周期        | 请求取消或组件已销毁；不重试旧实例                  |

非 Hosted 取令牌仅对可重试失败按 1、2、4 秒退避，最多重试 3 次；撤销或预算拒绝停止该重试。传输层自行恢复事件流时最多重连 5 次；界面可能接管恢复，不应另叠无限重试。

## 诊断入口 [#diagnostics]

保留失败时间、环境、公开 `agent_…` ID、HTTP 状态、错误码和 `X-Request-Id`，不记录凭证。在「运营与管理 → 签发记录」核对令牌状态，再用[会话回放](/docs/developers/agent/monitor)定位发生阶段。修复后按[测试嵌入接入](/docs/developers/agent/embed/testing)复测；字段契约见[智能体 API](/docs/api/native/agent)。