Handling OAuth 2.0 errors

01. April 2025

Table of Contents

Authorization error response Token error response Reporting errors to the user Error reference

FotoWeb may reject authorization because the user does not have permission to use a client as requested or because the client is not registered or allowed to be used with FotoWeb, for example. Authorization may also fail due to network or server issues, and it may be aborted or discontinued by the user, for example, because the user is unable to log in. Depending on the type of error and when it occurs, it might be reported.

... to the client, in the redirection URI from the authorize endpoint
... to the client, in the response to the token endpoint
... directly to the user via the user agent (browser)

Note: The FotoWeb authorize endpoint will NEVER redirect if the redirection URI is invalid or ambiguous, if the client is not registered, or if the client_id is missing or invalid. In such cases, FotoWeb will show an error page directly to the user without reporting the error to the client. This is usually a sign of an incorrectly configured integration. For details, see Application registration. A native client that opens a browser window for authorization SHOULD attempt to detect when the user closes the window without completing the authorization process. If this is not possible, the client's user interface can provide a Cancel or Retry button or have a timeout, after which the authorization process is aborted. Possible error responses to the client (via redirect or from the token endpoint) are described below. For a list of possible errors and their causes, see OAuth 2.0 Error Reference.

Authorization error response

The authorize endpoint may report errors by redirecting to the redirection endpoint of the client by adding the query parameters described below. If the redirect_uri parameter was given in the authorize request, then the error response will be redirected to the URI given in redirect_uri (assuming it is valid and registered).

https://myapplication.com/oauth2/callback?
 error=ERROR_TYPE&
 error_description=ERROR_DESCRIPTION&
 error_uri=ERROR_URI&
 state=STATE

Note: Even for error responses, the client MUST validate the state parameter before doing anything that may have any side effect other than logging.

Parameter	Description
`error`	If this parameter is present, then an error has occurred. An error code that identifies the type of the error. May be used programmatically by the client to perform different actions or show different standard error messages based on the type of error that has occurred. A reference of possible error codes can be found here. Error codes are also described by the OAuth standard (RFC 6749)A client MAY show this error code to the user or log it for the purpose of troubleshooting (by an integration developer or by Fotoware support).
`error_description`	OPTIONAL. This parameter MAY or may not be present, even if an error has occurred. Human-readable description of the error to assist the client developer in understanding the error. This description MAY be shown to the user, but is not necessarily useful or understandable for the user and may not be localized to the user's language. According to the OAuth 2.0 specification, the error description is encoded as ASCII. FotoWeb uses the entire Unicode set, encoded as UTF-8 and URL-encoded if necessary.
`error_uri`	OPTIONAL. This parameter MAY or may not be present, even if an error has occurred. URL of a page with a human-readable description of the error. The client MAY open this URL in a browser view to inform the user or client developer about the error, but the information shown is not necessarily useful or understandable for the user and may not be localized to the user's language.
`state`	The exact value of the `state` parameter sent by the client in the `authorize` request. The client MUST check that this value is identical to the value it sent earlier to protect against cross-site request forgery (CSRF) attacks. If the values do not match, the client MUST reject the request. This can be done, for example, by showing an error page. The client MUST NOT proceed with the authorization process and SHOULD NOT do anything that can affect its state other than logging. The client MAY also use this value to identify an individual session and/or authorization process (and in that case, reject the request if no session with a matching ID is found).

Token error response

The token endpoint reports errors with an HTTP status code of 400-599 and the following content.

Note: Under some unexpected circumstances (such as server or network-related issues), the response may have a different and unspecified format. Clients MUST handle this case and SHOULD treat it as an unexpected error. Users SHOULD then have the option to retry authorization.

400 BAD REQUEST
Content-Type: application/json
{
 "error": "ERROR",
 "error_description": "DESCRIPTION",
 "error_uri": "URL"
}

where

Parameter	Description
`error`	If this parameter is present, then an error has occurred. An error code that identifies the type of the error. May be used programmatically by the client to perform different actions or show different standard error messages based on the type of error that has occurred. A reference of possible error codes can be found here. Error codes are also described by the OAuth standard (RFC 6749)A client MAY show this error code to the user or log it for the purpose of troubleshooting (by an integration developer or by Fotoware support).
`error_description`	OPTIONAL. This parameter MAY or may not be present, even if an error has occurred. Human-readable description of the error to assist the client developer in understanding the error. This description MAY be shown to the user, but is not necessarily useful or understandable for the user and may not be localized to the user's language. According to the OAuth 2.0 specification, the error description is encoded as ASCII. FotoWeb uses the entire Unicode set, encoded as a usual JSON string.
`error_uri`	OPTIONAL. This parameter MAY or may not be present, even if an error has occurred. URL of a page with a human-readable description of the error. The client MAY open this URL in a browser view to inform the user or client developer about the error, but the information shown is not necessarily helpful or understandable for the user and may not be localized to the user's language.

Reporting errors to the user

If OAuth 2.0 authorization fails, the user needs to be notified.

Most of the user experience of OAuth 2.0 is in the browser view, and at least the authentication (log-in) interface is provided by FotoWeb. As discussed above, the client's only responsibility in this scenario is to allow the user to abort the authorization process.

In case FotoWeb returns an error response, the client should present an appropriate user-friendly and (if necessary) localized error message. It is sufficient to tell the user that authorization of the application has failed, and it is recommended to also inform the user who to contact in case of repeated failures (e.g., a support email of the client or the administrator of the FotoWeb server). The error_description attribute and the page linked to by the error_uri attribute are intended for diagnostic purposes for client developers and should not shown by the user. However, the client may present a Details button that displays this information, and there is no security risk in showing this information to regular users.

Error reference

A complete error reference for OAuth 2.0.

Handling OAuth 2.0 errors

Authorization error response

Token error response

Reporting errors to the user

Error reference

Related Articles