OpenMax
免费试用

错误码

登录、令牌、嵌入相关的错误码,以及错误响应格式。

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 · 错误。