Rate this page

Errors

Clients should be prepared to handle authorization and authentication errors received from the authorization or token endpoints.

Authorization errors

If an error occurs as the result of an authorization request, then the server will respond in one of two ways:

  1. If the redirect_uri is invalid or otherwise unusable, or if the client_id is missing or invalid, then the server will not be able to send an error back to the client, so it will display an error message directly to the end user.
  2. Otherwise, the server will redirect to the redirect URI, appending the error and error_description parameters.

Example authorization error:

https://example.com:443/callback?error=invalid_scope
&error_description=Undefined+scope+with+name+%27invalid_scope%27

For the authorization code grant type, error parameters will be appended to the URL as standard query parameters. For the implicit grant type, error parameters will be added to the URL fragment.

Field Type Provided? Description
error string always A machine-readable error code.
error_description string A human-readable error description.

Possible values for error are defined in the following table:

Error code Description
invalid_request The authorization request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed.
invalid_client An invalid client ID was provided.
invalid_grant The authorization grant is invalid, expired, revoked, does not match the redirect URI originally provided, or does not match the client that made the original request. This is most likely to occur when an expired authorization code is used.
invalid_scope The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
unsupported_grant_type The client specified an authorization grant type that is not supported.
unsupported_response_type The client specified an unsupported response_type value.
unauthorized_client The client attempted to use a grant type that it is not registered to use.
access_denied The resource owner or a policy denied the request.
login_required The client provided prompt=none, but the end user is not logged in, so the request cannot proceed.
consent_required The client provided prompt=none, but the end user has not consented to the requested scopes, so the request cannot proceed.
interaction_required End user interaction is required before the authentication can proceed. This will be returned, for example, when a client requests an ACR requiring a level of authentication that cannot be satisfied because the end user has not been set up for an authentication method required by the ACR.
server_error The server encountered an unexpected condition that prevented it from fulfilling the request.

Token errors

Errors returned by the token endpoint typically use an HTTP status of 400; the body is a JSON document consisting of a machine-readable error code and a human-readable error description. If client authentication fails, an HTTP status of 401 will be returned.

Field Type Provided? Description
error string always A machine-readable error code. See the table below.
error_description string A human-readable error description.
error_cause string A machine-readable error code indicating an authentication-related error. Only returned when using the password grant type. See the table below.

Possible values for error are defined in the following table:

Error code Description
invalid_request The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed.
invalid_client The client provided invalid client credentials.
invalid_scope The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
unauthorized_client The client attempted to use a grant type that it is not registered to use.
unsupported_grant_type The client specified an authorization grant type that is not supported.
access_denied The resource owner or a policy denied the request.
server_error The server encountered an unexpected condition that prevented it from fulfilling the request.

Possible values for error_cause are defined in the following table:

Error code Description
accountDisabled The account is disabled.
accountLocked The account is locked due to too many incorrect authentication attempts.
invalidCredentials The username and/or password is incorrect.
mustChangePassword The user’s current password must be changed.
invalidNewPassword A new password was provided that failed to satisfy the user’s password requirements.