Errors and troubleshooting

OneiD reports errors with the standard OAuth 2.0 error codes. Where the error appears depends on the endpoint: at your redirect URI, as JSON from the token endpoint, or on OneiD’s own error page when it cannot safely redirect. This page lists every error, then walks through common problems.

Error response format

Errors at your redirect URI

Errors from the authorize endpoint are sent to your redirect URI with these parameters:

HTTP/1.1 302 Found
Location: https://app.example.com/callback?error=login_required&error_description=The+user+must+sign+in.&state=Xk3fQ9vLp2&iss=https%3A%2F%2FYOUR_ONEID%2F

With response_mode=form_post, the same parameters arrive as a posted form.

Errors on OneiD’s error page

If the client_id is unknown or the redirect_uri is not registered for the client, OneiD does not redirect to your application. It shows its own error page with invalid_request. Logout errors are also shown on OneiD’s page; the browser is not redirected.

Errors from the token endpoint and other back-channel endpoints

The token, introspection and revocation endpoints answer errors with a JSON body and an HTTP status:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store

{
  "error": "invalid_grant",
  "error_description": "..."
}

The body may contain other fields, such as error_uri. Ignore fields you do not use. Branch on error, never on error_description.

The userinfo endpoint answers a missing, expired or revoked access token with HTTP 401 and a WWW-Authenticate: Bearer header.

Error codes

Troubleshooting

OneiD shows an error page instead of returning to my application

Symptom: after the redirect to OneiD, the browser stays on a OneiD error page with invalid_request.

Cause: the client_id is unknown, or the redirect_uri does not exactly match one registered for the client. OneiD compares redirect URIs exactly: scheme, host, port, path and trailing slash. There are no wildcards. https is required except for loopback addresses (localhost, 127.0.0.1, [::1]).

Fix: compare the redirect_uri in the request with the registered list character by character. Ask your administrator to register the exact value. See Client settings.

invalid_client or unauthorized_client

Symptom: the token endpoint returns invalid_client (HTTP 401), or the authorize or logout endpoint returns unauthorized_client.

Cause: invalid_client means client authentication failed: unknown client ID, wrong secret, expired secret or disabled client. unauthorized_client at authorize and logout means the client is disabled.

Fix: check that you send the right client ID and secret, with client_secret_basic or client_secret_post. If the secret was replaced, use the new one. Ask your administrator whether the client is enabled and the secret has not expired.

invalid_grant at the token endpoint

Symptom: exchanging a code or refreshing tokens returns invalid_grant.

Cause: one of:

• The code was already used. Codes are single-use; reloading the callback page sends the same code again.
• The code expired. Codes are valid for 5 minutes.
• The code_verifier does not match the code_challenge, often because the verifier was lost or replaced between the redirect and the callback.
• The refresh token expired, was revoked, or was used a second time after the grace period.
• The user was deleted or locked, or must change their password or enrol in MFA.

Fix: exchange the code once, right away, and do not reload the callback page. Keep the code verifier with the state until the callback. After a refresh, store the new refresh token. When invalid_grant persists, start a new sign-in.

invalid_scope

Symptom: the authorize or token endpoint returns invalid_scope.

Cause: the client asked for a scope it is not allowed.

Fix: request only the scopes allowed for the client, or ask your administrator to allow the scope. API scopes such as orders.read must be created and allowed by an administrator first.

access_denied

Symptom: the callback receives error=access_denied.

Cause: the user refused consent on the consent page.

Fix: handle it as a normal outcome. Explain that the application needs the permission and offer to try again.

HTTP 429 Too Many Requests

Symptom: a request returns HTTP 429 with "error": "slow_down".

Cause: the client sent too many requests in a short time.

Fix: wait the number of seconds in the Retry-After header, then retry with backoff. Cache tokens until they expire instead of requesting a new one per call. See Rate limits.

CORS error in the browser console

Symptom: a browser application shows a CORS error when its library calls the token, userinfo or revocation endpoint.

Cause: the application’s origin is not registered as an allowed CORS origin on an enabled client.

Fix: ask your administrator to add the origin, in the form scheme://host[:port] with no path, to the client’s allowed CORS origins. Changes take effect within about 15 seconds. Introspection never allows cross-origin requests. See Browser applications and CORS.

.NET: “Correlation failed”

Symptom: an ASP.NET Core application returns from OneiD and fails with “Correlation failed”.

Cause: the application runs on plain http. The browser does not send back the correlation cookie that the OpenID Connect handler set before the redirect.

Fix: run the application on https, also in development, and register the https redirect URI for the client.

Learn more

• Endpoints
• Rate limits
• Security best practices