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 cookies (if any) and send a 401 to the frontend.

NodeJS
GoLang
Python

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) => {                    // TODO: Write your own logic and then send a 401 response to the frontend                },            }        })    ]});

import (    "net/http"
    "github.com/supertokens/supertokens-golang/recipe/session"    "github.com/supertokens/supertokens-golang/recipe/session/sessmodels"    "github.com/supertokens/supertokens-golang/supertokens")
func main() {    supertokens.Init(supertokens.TypeInput{        RecipeList: []supertokens.Recipe{            session.Init(&sessmodels.TypeInput{                ErrorHandlers: &sessmodels.ErrorHandlers{                    OnUnauthorised: func(message string, req *http.Request, res http.ResponseWriter) error {                        // TODO: Write your own logic and then send a 401 response to the frontend                        return nil                    },                },            }),        },    })}

from supertokens_python import init, InputAppInfofrom supertokens_python.recipe import sessionfrom supertokens_python.framework import BaseRequest, BaseResponse
async def unauthorised_callback(req: BaseRequest, err: str, response: BaseResponse):    # TODO: Write your own logic and then send a 401 response to the frontend    return response
init(    app_info=InputAppInfo(api_domain="...", app_name="...", website_domain="..."),    framework='...',     recipe_list=[        session.init(            error_handlers=session.InputErrorHandlers(                on_unauthorised=unauthorised_callback            )        )    ])

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.

NodeJS
GoLang
Python

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 (message, request, response) => {                    // TODO: Write your own logic and then send a 403 response to the frontend                },            }        })    ]});

import (    "net/http"
    "github.com/supertokens/supertokens-golang/recipe/session"    "github.com/supertokens/supertokens-golang/recipe/session/claims"    "github.com/supertokens/supertokens-golang/recipe/session/sessmodels"    "github.com/supertokens/supertokens-golang/supertokens")
func main() {    supertokens.Init(supertokens.TypeInput{        RecipeList: []supertokens.Recipe{            session.Init(&sessmodels.TypeInput{                ErrorHandlers: &sessmodels.ErrorHandlers{                    OnInvalidClaim: func(validationErrors []claims.ClaimValidationError, req *http.Request, res http.ResponseWriter) error {                        // TODO: Write your own logic and then send a 403 response to the frontend                        return nil                    },                },            }),        },    })}

from supertokens_python import init, InputAppInfofrom supertokens_python.recipe import sessionfrom supertokens_python.recipe.session.exceptions import ClaimValidationErrorfrom supertokens_python.framework import BaseRequest, BaseResponsefrom typing import List
async def invalid_claim_callback(req: BaseRequest, invalid_claims: List[ClaimValidationError], response: BaseResponse):    # TODO: Write your own logic and then send a 403 response to the frontend    return response
init(    app_info=InputAppInfo(        api_domain="...", app_name="...", website_domain="..."),    framework='...',      recipe_list=[        session.init(            error_handlers=session.InputErrorHandlers(                on_invalid_claim=invalid_claim_callback            )        )    ])

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.

NodeJS
GoLang
Python

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) => {                    // TODO: Write your own logic and then send a 401 response to the frontend                },            }        })    ]});

import (    "net/http"
    "github.com/supertokens/supertokens-golang/recipe/session"    "github.com/supertokens/supertokens-golang/recipe/session/sessmodels"    "github.com/supertokens/supertokens-golang/supertokens")
func main() {    supertokens.Init(supertokens.TypeInput{        RecipeList: []supertokens.Recipe{            session.Init(&sessmodels.TypeInput{                ErrorHandlers: &sessmodels.ErrorHandlers{                    OnTokenTheftDetected: func(sessionHandle, userID string,                        req *http.Request, res http.ResponseWriter) error {                        // TODO: Write your own logic and then send a 401 response to the frontend                        return nil                    },                },            }),        },    })}

from supertokens_python import init, InputAppInfofrom supertokens_python.recipe import sessionfrom supertokens_python.framework import BaseRequest, BaseResponse
async def token_theft_detected_callback(req: BaseRequest, session_handle: str, user_id: str, response: BaseResponse):    # TODO: Write your own logic and then send a 401 response to the frontend    return response
init(    app_info=InputAppInfo(api_domain="...", app_name="...", website_domain="..."),        framework='...',     recipe_list=[        session.init(            error_handlers=session.InputErrorHandlers(                on_token_theft_detected=token_theft_detected_callback            )        )    ])