OAuth 2.0 Error Reference

Last updated
Save as PDF
Share
1. Share
2. Tweet
3. Share

This is an overview of errors that may occur during the OAuth 2.0 authorization process.

Tips for dealing with OAuth 2.0 errors can be found in Handling OAuth 2.0 Errors.

Most of these errors are returned as error responses to the redirection endpoint of the application. The application should handle them by displaying an appropriate, friendly error message to the user. Other errors are unexpected due to incorrect configuration, application implementation, or application registration. These may show up in the user's browser as error pages from FotoWeb (aka "kittens") because redirection to the application's endpoint URL would be a security risk or is simply not possible due to lack of a redirection URI.

This reference is grouped by what is causing the error and who is responsible for it:

The developer of the application
The administrator of FotoWeb (application registration, access control, ...)
The user (trying to use an application without permission)

Errors due to access control

These errors are caused by the user not having permission to use an application.

This is usually correct behavior, and applications should show friendly error messages to the user, maybe with information about who to contact or what to do if access was denied in error.

Note: The Error Code in the below table corresponds to the error parameter in an error response.

Error code	HTTP	Error messages and notes
`access_denied`	403	Your account is not licensed to use this application On-premises: The application uses the selection widget, but the site does not have a selection widget license, and the user is not a plus user. See licensing details for more information.
`access_denied`	403	The site is not licensed for use of third-party applications On-premises: The application uses the FotoWeb API, but the site does not have an API license. SAAS: The application uses the FotoWeb API, but the tenant does not have API access enabled in its subscription plan
`access_denied`	403	This site is not licensed for this type of application On-premises: The site is not licensed to integrate with this type of application SAAS: The tenant's subscription plan does not allow integration with this type of application
`access_denied`	403	Your account does not have permission to use third-party applications This application uses the FotoWeb API, but the user accessing it does not have the "API Access" group permission. See group permissions for details.
`access_denied`	403	Your account does not have permission to use this application The application is registered with an access list, and the user does not have permission to use it.
`access_denied`	403	You did not give this application permission to access the site The user has denied the application access to their account.
`access_denied`	403	Legacy CMS integrations are disabled on this site On-premises: The application uses the legacy method of embedding the selection widget, but the "Legacy Selection Widget" option is not enabled on this site. SAAS: The application uses the legacy method of embedding the selection widget, which is not supported in SAAS.

Errors due to invalid credentials

These errors are caused by invalid or expired tokens.

If the request was "legit", it may be caused by using expired tokens or authorization codes, which are limited in lifetime. You may also see these errors if you have made changes to the application registration and are sending tokens or codes received before the changes were made.

These errors may also be the result of replay attacks or other attempts to gain access without authorization.

Error code	HTTP	Error messages and notes
`invalid_authorization_code`	400	The authorization code is invalid or has expired The application has sent a request to get a token using an authorization code, but the authorization code is invalid or has expired.
`invalid_refresh_token`	400	The refresh token is invalid or has expired The application has requested a new access token using a refresh token, but the refresh token is invalid or has been revoked.
`client_authentication_failed`	403	The identity of this application could not be verified The application requires a client secret, but no `client_secret` was sent in the request, or the given client secret was incorrect.

Error code

HTTP

Error messages and notes

invalid_authorization_code

400

The authorization code is invalid or has expired

The application has sent a request to get a token using an authorization code, but the authorization code is invalid or has expired.

invalid_refresh_token

400

The refresh token is invalid or has expired

The application has requested a new access token using a refresh token, but the refresh token is invalid or has been revoked.

client_authentication_failed

403

The identity of this application could not be verified

The application requires a client secret, but no client_secret was sent in the request, or the given client secret was incorrect.

Errors due to incorrect implementation or configuration

If you see any of these errors, it means that the application is either implemented or registered incorrectly. Either way, there is a mismatch between the way the application was registered and the way it requests access to FotoWeb. Different types of applications need to be registered in different ways and require different requests and protocols for authorization.

Steps to resolve these errors:

Is the type of application clearly specified (for example, native vs. web, required permissions, etc.)?
Is the application registered correctly? See the documentation regarding application registration.
Is the application implemented correctly? See the documentation regarding correct implementation.

In the explanations of the errors below, we assume the application is registered correctly and the implementation is wrong.

Error code	HTTP	Error messages and notes
`invalid_client`	403	This application is not registered on the site The application is not registered or an incorrect `client_id` was specified in the request.
`unsupported_response_Type`	400	This application does not support the requested authorization flow and response type This means that the `response_type` and form of authorization request is not as expected for this type of application.
`invalid_request`	400	This application requires PKCE, but no acceptable code challenge method was specified The application is a native application, and the client is using authorization code flow. This requires PKCE to prevent the hijacking of authorization codes.
`invalid_request`	400	The redirection URI parameter is unexpected The application has sent a token request with a `redirect_uri` parameter, but this is unexpected unless `grant_type` is set to `authorization_code`. (i.e., a request to get a token using an authorization code).
`unsupported_grant_type`	400	The requested grant type is not supported The application has sent a token request, but the requested `grant_type` is not implemented or supported by this type of application or FotoWeb.
`invalid_request`	400	The redirection URI is malformed or not allowed The application has specified a `redirect_uri` in a request, and the URI is not a valid URL, is incorrectly encoded, or is not allowed in general.
`invalid_request`	400	The redirection URI is not registered with this application The application has specified a `redirect_uri` in a request, and the URI is not registered.
`invalid_request`	400	This application has multiple registered redirection URIs, but none was specified The application has NOT specified a `redirect_uri` in a request, but multiple redirect URIs are registered, so the application must specify one in this request.