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.
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.