Error codes

This page documents the error codes returned by ID.me’s OAuth 2.0 endpoints during authorization, logout, and token exchange flows.

These error codes apply to both OAuth 2.0 and OpenID Connect integrations, as OIDC uses the same underlying OAuth 2.0 endpoints

Authorization code and implicit token flow

If the authorization request cannot be completed, ID.me appends error parameters to your redirect_uri when redirecting the user.

All responses are returned with HTTP 200.

Example

1 https://example.com/callback?error=invalid_scope&error_description=scope+cant+be+resolved+to+an+existing+policy+for+the+client

Error	Description
invalid_request	`client_id`, `response_type`, or `redirect_uri` is missing
invalid_client	`client_id` cannot be resolved to an application (OAuth client value mismatch)
invalid_scope	`scope` cannot be resolved to an existing policy for the client
invalid_redirect_uri	`redirect_uri` cannot be resolved to any of the configured redirect URIs for the consumer
unsupported_response_type	`response_type` is not `code` or `token`

Logout

If a logout request is malformed or cannot be processed, ID.me returns error parameters on the redirect.

All responses are returned with HTTP 200.

Error codes

Error	Description
invalid_request	`client_id` or `redirect_uri` is missing
invalid_client	`client_id` cannot be resolved to a consumer
invalid_redirect_uri	`redirect_uri` cannot be resolved to any of the configured redirect URIs for the consumer

Token exchange and refresh

When exchanging an authorization code for an access token, refreshing a token, or using the password grant, errors are returned in the JSON response body.

All responses are returned with HTTP 400 (Bad Request).

Example

1 {
2   "error": "invalid_grant",
3   "error_description": "The provided authorization grant is expired or revoked"
4 }

All grant types

The following errors apply regardless of grant type:

Error	Description
invalid_request	`scope`, `grant_type`, `client_id`, or `client_secret` is missing
invalid_client	`client_id` and `client_secret` cannot be resolved to a consumer
invalid_scope	`scope` cannot be resolved to an existing policy for the client
unauthorized_client	Consumer is not allowed to use the provided `grant_type`

Authorization code

Error	Description
invalid_request	`code` or `redirect_uri` is missing
invalid_grant	The code provided does not match any existing grants
invalid_redirect_uri	`redirect_uri` cannot be resolved to any of the configured redirect URIs for the consumer
invalid_grant	The provided authorization grant is invalid
invalid_grant	The provided authorization grant does not match the redirection URI used in the authorization request
invalid_grant	The provided authorization grant was issued to another client
invalid_grant	The provided authorization grant is expired or revoked

The invalid_grant error may be returned for several distinct reasons. Use the error_description field in the response to determine the specific cause.

Password grant

Error	Description
invalid_request	`email` or `password` is missing
invalid_resource_owner	User cannot be authenticated with the given credentials

Refresh token

Error	Description
invalid_request	`refresh_token` is missing
invalid_grant	The refresh token provided is invalid
invalid_grant	The refresh token provided has already been used
invalid_grant	The refresh token provided was issued to another client
invalid_grant	The refresh token provided has expired

Best practice

Always check for the error parameter in redirect URI responses and handle it gracefully
Log error codes and descriptions to assist with debugging and support requests
Use the error_description field to differentiate between multiple causes of the same error code, especially invalid_grant
Map error codes to user-friendly messages rather than exposing raw error strings to end users
Handle access_denied explicitly, as this indicates the user denied the authorization request and should be routed back to an appropriate page in your application