Error codes
Error codes for sign-in, tokens and embedding, and the error response format.
Apps API error codes (full list): not yet published. Until the platform publishes them, this page lists the sign-in and embedding error codes; the platform-wide list will be added here.
Error response format
Errors from /api/v1/* are HTTP problem JSON (application/problem+json); the error code is in the response body. Handle the HTTP status first, then look at the code when you need finer detail.
Sign-in and tokens
error= in the callback
| Error | Meaning | What the app should do |
|---|---|---|
login_required |
The member has no Workspace sign-in state. Only official apps in active status receive it | Show "Please sign in to Workspace first" + a "Sign in again" button (at top level you can redirect to authorization once more; in an iframe offer "Open in new tab"). Do not redirect again automatically |
access_denied |
The app is not installed in this organization or is disabled, or the member's role cannot see any entry | Show a no-permission page; do not retry |
invalid_scope |
scope exceeds the approved range |
Fix the request parameters (development-time error) |
invalid_request / unsupported_response_type |
Missing or malformed parameters (state, PKCE, nonce too long, etc.) | Fix the code; show a generic failure page |
| Other / unknown | — | Generic failure page + "Sign in again" |
Workspace authorization page final states (never return to your redirect_uri)
| Error | Meaning | What the app should do |
|---|---|---|
APP_AUTHORIZE_LOGIN_REQUIRED |
An organization app was accessed without sign-in state (the platform does not trust an organization app's redirect_uri when not signed in) | The authorization page shows "Please sign in to Workspace first": at top level it offers "Sign in to Workspace" and continues automatically after sign-in; in an iframe it offers "Sign in in a new tab" + "I've signed in, continue" |
APP_AUTHORIZE_CLIENT_INVALID |
client_id missing or unknown, or the official app is not active | Check the App ID |
APP_AUTHORIZE_REDIRECT_URI_INVALID |
redirect_uri is not byte-for-byte identical to the value registered in the installed version's manifest | Check your configuration |
APP_ORGANIZATION_MISMATCH |
The app belongs to another of the member's organizations | The authorization page offers "Switch to {organization} and continue" |
APP_PRINCIPAL_KIND_INVALID |
Agents cannot open apps | — |
APP_AUTHORIZE_RATE_LIMITED |
about 60 / minute per member (approximate, not guaranteed); without a session, limited by client address (429 + Retry-After) |
This is the backstop against redirect loops; hitting it means your app is looping |
Token endpoint
| Error | Meaning | What the app should do |
|---|---|---|
invalid_request |
Missing code_verifier, malformed, etc. (the code is still usable) |
Fix the code |
invalid_grant |
The code was already used, expired, verifier mismatch (code voided), redirect_uri mismatch, or a refresh_token was replayed | Treat it as a sign-in failure and let the user retry manually once |
invalid_client (401) |
Wrong App ID / Secret, or a user token / PAT was used | Check the Secret (after rotation the old Secret is kept for 24 hours) |
Calling /api/v1/*
| Status | Meaning | What the app should do |
|---|---|---|
| 401 | Token expired, or installation disabled / uninstalled / narrowed (APP_INSTALLATION_INACTIVE), or the member has left |
Clear the session and re-authorize (silently): at top level, redo the redirect authorization; when embedded, request an authorization code from the host again (see "Sign-in when embedded"), no redirect. If it fails again, stay on an explanation page |
| 403 | Missing scope (AUTH_APP_INSUFFICIENT_SCOPE), or this person has no permission |
Show no-permission; do not re-authorize |
When embedded in Workspace
Requesting an authorization code from the host
Host codes and codes decided by the SDK itself never share a name, so the code tells you who gave up.
| Error code | Decided by | Meaning | What the app should do |
|---|---|---|---|
not_embedded |
SDK | Not embedded in another page (new tab / top level / opened directly) | Use redirect sign-in, the only case where redirecting is allowed |
host_timeout |
Host | The host got no result from issuing within 8 seconds, gave up on this attempt, and immediately released the in-flight slot | Request again right away (limited retries) |
timeout |
SDK | No reply from the host within timeoutMs (default 10 seconds), for example an older host that does not recognize this message |
Request again (limited retries) |
busy |
Host | This iframe already has a request in flight (usually only when you set timeoutMs below 8 seconds) |
Wait a moment (about 1 second) and request again (limited retries) |
access_denied |
Host | Not installed or disabled, or the current role cannot see any entry | Show no-permission; do not retry |
login_required |
Host | The Workspace session has expired | Ask the user to sign in to Workspace again first (refresh the Workspace page); offer "Open in new tab" |
rate_limited |
Host | Too frequent (see Rate limits); you may retry after retryAfter seconds |
Show the error; the "Retry" button must not fire before retryAfter |
client_invalid |
Host | Invalid app, or redirectUri is not byte-for-byte identical to the registered value |
Check redirectUri (development-time error) |
invalid_scope |
Host | Requested an unapproved scope | Fix the scope (development-time error) |
invalid_request |
Host | Malformed fields (challenge not 43 characters, method not S256, invalid redirectUri / nonce / scope format) | Fix the code |
failed |
Host | Other failures (including unknown codes) | Error + "Open in new tab" |
unsupported |
SDK | The browser has no Web Crypto, or the page is not an https secure context | Fix the deployment; error + "Open in new tab" |
aborted |
SDK | disconnect() was called while waiting |
Usually nothing to do |
Requesting to open a conversation
| Code | Returned by | Details |
|---|---|---|
invalid_request, unsupported_target, activation_required, rate_limited, failed |
Host, openmax:navigate:error |
Open modes and URLs › App requests to open a conversation |
Chat SDK
Chat SDK errors are listed in the SDK reference: @openmaxai/chat-sdk · Errors and @openmaxai/chat-openmax · Errors.
