# Sign-in errors

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](/errors/) 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](/hosted-portal/intents/).

For recorded attempts, inspect [history and timelines](/sso/sign-in-history/). For a connection test, read [Connection Doctor](/hosted-portal/connection-doctor/); a refused attempt is not guaranteed to have a durable history entry.
