Customizing Error Handling

SuperTokens session recipie can throw the following errors:

Unauthorised error

• Thrown when a protected backend API is accessed without a session.
• The default bahaviour of this is to clear session tokens (if any) and send a 401 to the frontend.

import SuperTokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";

SuperTokens.init({
    supertokens: {
        connectionURI: "...",
    },
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init({
            errorHandlers: {
                onUnauthorised: async (message, request, response, userContext) => {
                    // TODO: Write your own logic and then send a 401 response to the frontend
                },
            }
        })
    ]
});

Invalid claim error

• Thrown when a protected backend API is accessed with a session that doesn't pass the claim validators
• The default bahaviour of this is to send a 403 to the frontend with the errors includes in the body.

import SuperTokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";

SuperTokens.init({
    supertokens: {
        connectionURI: "...",
    },
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init({
            errorHandlers: {
                onInvalidClaim: async (validatorErrors, request, response, userContext) => {
                    // TODO: Write your own logic and then send a 403 response to the frontend
                },
            }
        })
    ]
});

Token theft detected

• Thrown when a session hijacking attempt has been detected.
• We detect this using rotating refresh tokens.
• The default behaviour of this is to revoke the session and send a 401 to the frontend.

import SuperTokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";

SuperTokens.init({
    supertokens: {
        connectionURI: "...",
    },
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init({
            errorHandlers: {
                onTokenTheftDetected: async (sessionHandle, userId, req, res, userContext) => {
                    // TODO: Write your own logic and then send a 401 response to the frontend
                },
            }
        })
    ]
});

Try Refresh Token

• Thrown when the access token is expired or invalid. This can also be thrown from the session refresh endpoint if multiple access tokens are present in the request cookies.
• The default bahaviour of this is to send a 401 to the frontend.

import SuperTokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";

SuperTokens.init({
    supertokens: {
        connectionURI: "...",
    },
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init({
            errorHandlers: {
                onTryRefreshToken: async (message, request, response, userContext) => {
                    // TODO: Write your own logic and then send a 401 response to the frontend
                },
            }
        })
    ]
});

Clear Duplicate Session Cookies

• Thrown when the refresh session API clears session cookies from the olderCookieDomain because multiple access tokens were found in the request cookies. See this issue for more information.
• The default bahaviour of this is to send a 200 to the frontend.

import SuperTokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";

SuperTokens.init({
    supertokens: {
        connectionURI: "...",
    },
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init({
            errorHandlers: {
                onClearDuplicateSessionCookies: async (message, request, response, userContext) => {
                    // TODO: Write your own logic and then send a 200 response to the frontend
                },
            }
        })
    ]
});