嵌入限制与错误

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

限制

项目	值与单位	来源
`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 的预算字段为美分。会话预算耗尽后不能继续提交新的工作；保留工具确认和中断入口。

服务端错误

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

EMBED_TOKEN_EXPIRED

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

EMBED_TOKEN_REVOKED

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

EMBED_ORIGIN_NOT_ALLOWED

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

EMBED_USER_BLOCKED

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

EMBED_RATE_LIMITED

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

EMBED_BUDGET_EXHAUSTED

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

EMBED_MONTHLY_CAP_REACHED

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

EMBED_FIELD_NOT_ALLOWED

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

其他拒绝

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

会话权限、归档和事件内容错误见智能体限制与错误。

Kit 错误与重试

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 次；界面可能接管恢复，不应另叠无限重试。

诊断入口

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

嵌入限制与错误

本页内容