Errors

What each OAuth 2.0 / OpenID Connect error means when integrating with NIA — where it shows up, why it happens, and how to fix it.

How errors are returned

NIA reports errors in two places, depending on the step:

Authorization endpoint — errors come back as query parameters on your redirect_uri, so your callback route should handle them:

redirect

https://app.example.com/auth/callback?error=access_denied&error_description=...&state=...

Token, UserInfo, introspection & revocation — errors come back as a JSON body with an error field and HTTP 4xx:

response

{
  "error": "invalid_grant",
  "error_description": "Authorization code is invalid, expired, or already used."
}

error	Meaning	Fix
`invalid_request`	A required parameter is missing or malformed	Check response_type=code, client_id, redirect_uri, scope, and PKCE params
`unauthorized_client`	The client may not use this grant/response type	Enable authorization_code for the client in the dashboard
`access_denied`	The user declined consent, or a policy blocked it	Expected when the user clicks Deny — handle it gracefully
`unsupported_response_type`	response_type is not code	NIA only supports response_type=code
`invalid_scope`	A requested scope is not allowed for this client	Add the scope to the client's allowed scopes
`server_error`	Unexpected error on NIA's side	Retry; if it persists, contact support

error	Meaning	Fix
`invalid_client`	Client authentication failed	Check client_id / client_secret and the auth method (public clients send no secret)
`invalid_grant`	The code or refresh token is invalid, expired, used, or the redirect_uri / PKCE verifier doesn't match	Codes are single-use and short-lived; ensure redirect_uri matches and the code_verifier is correct
`unsupported_grant_type`	grant_type is not supported	Use authorization_code, refresh_token, or client_credentials
`invalid_request`	Missing or malformed parameter	Ensure Content-Type is application/x-www-form-urlencoded and all fields are present
`invalid_scope`	Requested scope exceeds what was granted	Request a subset of the originally granted scopes

Symptom	Cause	Fix
redirect_uri_mismatch	The redirect URI doesn't exactly match a registered one	Register the exact URI — no trailing slash, correct scheme/host/port/path
invalid_grant on PKCE	code_verifier missing or the session was lost between /authorize and /token	Persist the verifier in the session; ensure cookies survive the redirect (SameSite=Lax)
state / nonce mismatch	The session cookie didn't survive the round-trip	Check cookie domain, Secure, and SameSite settings
CORS blocked (SPA)	A browser client calls /token from an origin not on the allowlist	Add the app's origin to the client's CORS allowlist (browser/public clients only)
Signature verification failed	Server clock skew, or an unknown kid	Sync server time (NTP); refetch the JWKS by kid
Wrong issuer	Using dev-platform instead of the API host	The issuer is https://dev-api.niaauth.com