Skip to main content
Documentation & User Guides | Fotoware

OAuth 2.0 Error Reference

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.

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:

  1. Is the type of application clearly specified (for example, native vs. web, required permissions, etc.)?
  2. Is the application registered correctly? See the documentation regarding application registration.
  3. 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.