This page details the error codes returned by the Class OAuth 2.0 endpoints — the authorisation request, and token and refresh requests.
For HTTP status codes and the error envelope returned by the resource APIs, see Class API structure.
These codes are returned in the error parameter of the authorisation response, appended to your redirect_uri. They are defined in Section 4.1.2.1 of the OAuth 2.0 specification and Section 3.1.2.6 of the OpenID Connect specification.
| Error code | Meaning |
|---|---|
invalid_request | The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. |
unauthorized_client | The client is not authorised to request an authorisation code using this method. |
access_denied | The resource owner or authorisation server denied the request. |
unsupported_response_type | The authorisation server does not support obtaining an authorisation code using this method. |
invalid_scope | The requested scope is invalid, unknown, or malformed. |
server_error | The authorisation server encountered an unexpected condition that prevented it from fulfilling the request. This code exists because a 500 Internal Server Error status cannot be returned to the client via an HTTP redirect. |
temporarily_unavailable | The authorisation server is temporarily unable to handle the request, due to overloading or maintenance. This code exists because a 503 Service Unavailable status cannot be returned to the client via an HTTP redirect. |
login_required | The prompt parameter was set to none, but the user is not logged in to Class. |
consent_required | The prompt parameter was set to none, but there is no previous consent for one or more of the requested scope values. |
registration_not_supported | The request specified the OpenID Connect registration parameter, which the Class authorisation server does not support. |
request_not_supported | The request specified the OpenID Connect request parameter, which the Class authorisation server does not support. |
request_uri_not_supported | The request specified the OpenID Connect request_uri parameter, which the Class authorisation server does not support. |
login_required and consent_required are the expected responses when you use prompt=none to check silently for an existing session. Treat them as a signal to start an interactive authorisation, not as failures.
These codes are returned in the error property of the JSON response from the token endpoint, alongside an error_description containing a more specific, human-readable message. They are defined in Section 5.2 of the OAuth 2.0 specification.
| Error code | Meaning |
|---|---|
invalid_request | The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, uses more than one mechanism for authenticating the client, or is otherwise malformed. |
invalid_client | Client authentication failed. |
invalid_grant | The provided authorisation grant or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorisation request, or was issued to another client. |
unauthorized_client | The client is not authorised to request an access token using the specified grant type. |
unsupported_grant_type | The specified grant type is not supported by the authorisation server. |
invalid_scope | The requested scope is invalid, unknown, or malformed, or exceeds the scope granted by the resource owner. |
Error response format
{
"error": "invalid_client",
"error_description": "Client authentication failed"
}A few of these codes have causes that come up repeatedly.
invalid_client — usually a credentials mismatch rather than a malformed request. Check that you are using the credentials for the environment you are calling: PIE credentials sent to the production host, or the reverse, produce this error. Also check that the Authorization header is correctly Base64-encoded and that the word Basic is capitalised, since the header is case-sensitive.
invalid_grant on a refresh request — refresh tokens are single-use. Once you exchange one, it is immediately invalidated, and reusing it produces this error. Confirm you are storing and using the new refresh token returned with each token response. Refresh tokens also expire after 30 days, after which you must start a new authorisation flow. See Managing access and refresh tokens.
invalid_grant on a token request — authorisation codes are single-use and short-lived. This also occurs when the redirect_uri in your token request does not exactly match the one used in the authorisation request.
invalid_scope — check the access specifiers required by the endpoints you are calling, and confirm the scope you are requesting is a subset of what the user granted. See Authorisation Scopes.
- Class API structure — HTTP status codes and the resource API error envelope.
- Rate limiting — handling
429 Too Many Requests. - Environments — hosts and credentials per environment.