Skip to content
Dashboard
Theme
Theme

Sign-in errors

How sign-in failures are reported: every failure has a stable error code with a developer message, an IT-admin message and a doc_url that points to its page in the error code reference.

View Markdown

API failures use a stable error envelope with type, code, message, param, doc_url and request_id. Broker browser failures render an error page for the user or IT admin; do not assume every failure arrives at your callback as JSON.

Use the error reference for each code’s developer message and remediation. Keep the request ID when reporting a problem. Do not log authorization codes, tokens, complete profiles or SAML responses.

Failure Application response
invalid_grant or flow_interrupted_retry Discard the attempt and start a fresh sign-in
State mismatch, expired attempt or wrong browser session Reject the callback before token exchange
email_outside_verified_domain Ask the customer’s admin to check its domain and IdP account
connection_untested or connection_inactive Complete the test and activation steps
access_token_invalid Reject the token and require authentication again

The Node SDK throws RestartSignIn for interrupted or invalid exchanges. Other structured failures use OhAuthCatError; preserve its code and request ID without exposing sensitive details to a browser.

Portal states have their own UX meaning. Their catalogue status value is not an HTTP status to send to clients. See portal intents.

For recorded attempts, inspect history and timelines. For a connection test, read Connection Doctor; a refused attempt is not guaranteed to have a durable history entry.