错误码
登录、令牌、嵌入相关的错误码,以及错误响应格式。
Apps API 错误码(完整列表):暂未公开。 平台公开之前,这一页列出登录和嵌入相关的错误码;平台全部错误码公开后补在这里。
错误响应格式
/api/v1/* 出错时返回 HTTP problem JSON(application/problem+json),错误码在响应体里。先按 HTTP 状态处理,需要细分时再看错误码。
登录和令牌
回调里的 error=
| 错误 | 含义 | 应用怎么做 |
|---|---|---|
login_required |
成员没有 Workspace 登录态。只有状态为 active 的官方应用会收到它 | 显示「请先登录 Workspace」+「重新登录」按钮(顶层可以再跳一次授权;iframe 里给「新标签打开」)。不要自动再跳 |
access_denied |
应用没在本组织安装或已停用,或者成员的角色看不到任何入口 | 显示无权限页,不重试 |
invalid_scope |
scope 超出了已批准范围 |
改请求参数(开发期错误) |
invalid_request / unsupported_response_type |
参数缺失或格式错(state、PKCE、nonce 过长等) | 修代码;显示通用失败页 |
| 其他 / 不认识的 | — | 通用失败页 +「重新登录」 |
Workspace 授权页终态(不会回到你的 redirect_uri)
| 错误 | 含义 | 应用怎么做 |
|---|---|---|
APP_AUTHORIZE_LOGIN_REQUIRED |
没有登录态时访问组织应用(未登录时平台不信任组织应用的 redirect_uri) | 授权页显示「请先登录 Workspace」:顶层给「登录 Workspace」,登录后自动继续;iframe 里给「在新标签中登录」+「我已登录,继续」 |
APP_AUTHORIZE_CLIENT_INVALID |
client_id 缺失、不认识,或官方应用不是 active | 检查 App ID |
APP_AUTHORIZE_REDIRECT_URI_INVALID |
redirect_uri 和安装版本 manifest 里登记的值不是逐字节相同 | 检查配置 |
APP_ORGANIZATION_MISMATCH |
应用属于成员的另一个组织 | 授权页提供「切换到 {组织} 并继续」 |
APP_PRINCIPAL_KIND_INVALID |
Agent 不能打开应用 | — |
APP_AUTHORIZE_RATE_LIMITED |
每个成员约 60 次 / 分钟(近似值,不保证精确);没有会话时按客户端地址限流(429 + Retry-After) |
这是防重定向循环的兜底;撞到说明你的应用在循环 |
token 端点
| 错误 | 含义 | 应用怎么做 |
|---|---|---|
invalid_request |
缺少 code_verifier 或格式错等(code 仍可用) |
修代码 |
invalid_grant |
code 已用过、过期、verifier 不匹配(code 作废)、redirect_uri 不一致,或 refresh_token 被重放 | 当登录失败处理,允许用户手动重来一次 |
invalid_client(401) |
App ID / Secret 错,或用了用户 token / PAT | 检查 Secret(轮换后旧 Secret 保留 24 小时) |
调 /api/v1/*
| 状态 | 含义 | 应用怎么做 |
|---|---|---|
| 401 | token 过期,或安装停用 / 卸载 / 收窄(APP_INSTALLATION_INACTIVE),或成员已离开 |
清会话,重新授权(无感):顶层重走跳转授权;嵌入时重新向宿主要授权码(见「嵌入时登录」),不跳转。再失败就停在说明页 |
| 403 | 缺 scope(AUTH_APP_INSUFFICIENT_SCOPE),或这个人本身没有权限 |
显示无权限,不要重新授权 |
嵌入 Workspace 时
向宿主要授权码
宿主的码和 SDK 自己判定的码不重名,看 code 就知道是谁放弃的。
| 错误码 | 谁判的 | 含义 | 应用怎么做 |
|---|---|---|---|
not_embedded |
SDK | 没嵌在别的页面里(新标签 / 顶层 / 直接打开) | 走跳转登录——唯一允许跳转的情况 |
host_timeout |
宿主 | 宿主等签发 8 秒没有结果,已放弃这一次,并立即放开在途占位 | 马上再要一次(有限重试) |
timeout |
SDK | timeoutMs(默认 10 秒)内宿主没回音,比如宿主是不认这条消息的旧版本 |
再要一次(有限重试) |
busy |
宿主 | 这个 iframe 已有一个请求在途(一般只在你把 timeoutMs 设得短于 8 秒时出现) |
稍等(约 1 秒)再要(有限重试) |
access_denied |
宿主 | 没安装或已停用,或当前角色看不到任何入口 | 显示无权限,不重试 |
login_required |
宿主 | Workspace 会话已失效 | 提示先在 Workspace 重新登录(刷新 Workspace 页面);给「新标签打开」 |
rate_limited |
宿主 | 太频繁(见限流),retryAfter 秒后可以再试 |
显示错误;「重试」按钮不早于 retryAfter |
client_invalid |
宿主 | 应用无效,或 redirectUri 和登记的值不是逐字节相同 |
检查 redirectUri(开发期错误) |
invalid_scope |
宿主 | 请求了未批准的 scope | 修 scope(开发期错误) |
invalid_request |
宿主 | 字段格式不对(challenge 不是 43 位、method 不是 S256、redirectUri / nonce / scope 格式不对) | 修代码 |
failed |
宿主 | 其他失败(含不认识的码) | 错误 +「新标签打开」 |
unsupported |
SDK | 浏览器没有 Web Crypto,或页面不是 https 安全上下文 | 修部署;错误 +「新标签打开」 |
aborted |
SDK | 等待中调用了 disconnect() |
一般不用处理 |
请求打开会话
| 错误码 | 谁返回 | 详见 |
|---|---|---|
invalid_request、unsupported_target、activation_required、rate_limited、failed |
宿主,openmax:navigate:error |
打开方式与地址 › 应用请求打开会话 |
Chat SDK
Chat SDK 的错误见 SDK 参考:@openmaxai/chat-sdk · 错误、@openmaxai/chat-openmax · 错误。
