OpenMax
Free Trial

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.