Error reference

Standard OAuth 2.0 errors

These errors are returned via the query parameters of the redirect URL or in token endpoint responses.

Error code	HTTP status	Description	Common cause
invalid_request	400	The request is missing a required parameter	Missing client_id, redirect_uri, etc.
invalid_client	401	Client authentication failed	Wrong client_id or client_secret
invalid_grant	400	The grant is invalid	Code expired, already used, or wrong redirect_uri
invalid_scope	400	The requested scope is not allowed	Scope not registered for the client
unauthorized_client	401	The client is not authorized for the grant type	Flow not enabled for the client
unsupported_grant_type	400	The grant type is not supported	Using an unsupported flow
access_denied	403	The user denied authorization	The user clicked "Deny"
consent_required	400	Consent is required but prompt=none	Use an interactive flow
login_required	400	The user is not signed in but prompt=none	Use an interactive flow
server_error	500	The server encountered an error	Contact support
temporarily_unavailable	503	The server is temporarily unavailable	Try again later

Token validation errors

Error	HTTP status	Description	Resolution
invalid_token	401	The token is invalid or expired	Refresh or re-authenticate
insufficient_scope	403	The token lacks the required scope	Request additional scopes

Magic Link errors

The GET /api/magiclink/validate endpoint returns a numeric error code in the errorCode field of the response, along with an accompanying text explanation in the errorMessage field. The errorCode field is a number (not a string).

errorCode	Meaning	User action
1	Token not found (TokenNotFound)	Request a new magic link
2	Token expired (TokenExpired)	Request a new magic link
3	Token already used (TokenAlreadyUsed)	Request a new magic link
4	User account not found (UserNotFound)	Contact support
5	User account deactivated (UserNotActive)	Contact support
6	Account locked (UserLocked)	Wait or contact support
7	Invalid token format (InvalidTokenFormat)	Request a new magic link
8	Invalid ticket (InvalidTicket)	Request a new magic link

Example error response:

{
  "valid": false,
  "userGuid": null,
  "email": null,
  "errorMessage": "The magic link has expired.",
  "errorCode": 2
}

HTTP status code overview

Status code	Meaning	Common scenarios
200	Success	A successful request
302	Redirect	An OAuth redirect
400	Bad Request	Invalid parameters
401	Unauthorized	Invalid credentials or token
403	Forbidden	Access denied, insufficient scope
404	Not Found	The resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal error
503	Service Unavailable	Temporary unavailability

Error response formats

Authorization endpoint (via redirect)

https://myapp.com/callback?error=access_denied&error_description=User%20denied%20access&state=xyz

Token endpoint (JSON)

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired."
}

Error handling

// Example error handling
async function handleTokenResponse(response) {
  if (!response.ok) {
    const error = await response.json();

    switch (error.error) {
      case 'invalid_grant':
        // Code expired or invalid - restart the flow
        redirectToLogin();
        break;
      case 'invalid_client':
        // Configuration error - check the credentials
        console.error('Invalid client credentials');
        break;
      default:
        console.error('OAuth error:', error.error_description);
    }
  }
}