OAuthError
Errors are either returned in a JSON response body, or as redirect parameters depending on expected response type.
JSON Response#
When an error is returned from an OAuth endpoint as a JSON body the following structure can be expected in the response. The change_password_id field will only be present on the response if a password change is required.
Example JSON Response
{
"change_password_id": "a65f7ac3-e4ce-4bf6-bbb0-576189c4d965",
"error": "change_password_required",
"error_description": "The user is required to change their password.",
"error_reason": "change_password_breached"
}Redirect Parameters#
When an error is returned from an OAuth endpoint as a redirect, the errors are put on the redirect as query parameters.
Example HTTP Redirect
HTTP/1.1 302 Found
Location: https://piedpiper.com/callback?
error=unsupported_response_type
&error_reason=invalid_response_type
&error_description=Parameter+response_type+must+be+set+to+code+or+token.
&state=bEF7UItzlhNvE31Rf0_axShomu_vU30tMeJcqMZ9LfA0Error Fields#
Regardless of the way the error is returned to you, the field definitions are the same. Each possible value error and error_reason is documented below.
Error Parameters#
errorStringThe OAuth error response type. In most cases these values are defined or suggested by an RFC or other specification.
The possible values are:
access_deniedauthorization_pendingchange_password_requiredconsent_requiredexpired_tokeninteraction_requiredinvalid_clientinvalid_dpop_proofinvalid_grantinvalid_requestinvalid_scopeinvalid_targetinvalid_tokenlogin_requirednot_licensedserver_errortwo_factor_requiredunauthorized_clientunsupported_grant_typeunsupported_response_typeunsupported_token_type
error_descriptionStringThe human-readable OAuth error description. This description should describe the error condition and it may contain a parameter value that caused the error.
error_reasonStringThe OAuth error reason. These reason codes are defined by FusionAuth to provide you a specific reason code so that you may identify the specific reason the request failed. The defined error codes as defined by OAuth2 or OpenID Connect only provide general indications such as an invalid request that may be caused by more than one parameter. Each of the values returned in this field will represent a specific error.
The possible values are:
access_token_expiredaccess_token_failed_processingaccess_token_invalidaccess_token_malformedaccess_token_requiredaccess_token_unavailable_for_processingauth_code_not_foundauthentication_requiredchange_password_administrativechange_password_breachedchange_password_expiredchange_password_validationclient_authentication_missingclient_id_mismatchconsent_canceledconsent_requiredemail_verification_requiredgrant_type_disabledinvalid_additional_client_idinvalid_client_authenticationinvalid_client_authentication_schemeinvalid_client_idinvalid_device_codeinvalid_entity_permission_scopeinvalid_expires_ininvalid_grant_typeinvalid_id_token_hintinvalid_origininvalid_origin_opaqueinvalid_pkce_code_challengeinvalid_pkce_code_challenge_methodinvalid_pkce_code_verifierinvalid_post_logout_redirect_uriinvalid_promptinvalid_redirect_uriinvalid_response_modeinvalid_response_typeinvalid_target_entity_scopeinvalid_tenant_idinvalid_user_codeinvalid_user_credentialsinvalid_user_idlogin_preventedmissing_client_idmissing_client_secretmissing_codemissing_code_challengemissing_code_verifiermissing_device_codemissing_grant_typemissing_redirect_urimissing_refresh_tokenmissing_required_scopemissing_response_typemissing_tenant_idmissing_tokenmissing_user_codemissing_user_idmissing_verification_urimulti_factor_challenge_requirednot_licensedphone_verification_requiredrefresh_token_not_foundrefresh_token_type_not_supportedregistration_missing_requirementregistration_requiredregistration_verification_requiredunknownunknown_scopeuser_code_expireduser_expireduser_lockeduser_not_found
stateStringThe state that was provided on the Authorization request. This parameter is only returned during an HTTP redirect if it was provided on the initial request.