Customizing Error Handling

SuperTokens session recipie can throw the following errors:

• GENERAL_ERROR

  • The way to handle this error is to simply send a status code of 500. Or try to call the function once again after a while.

• BAD_INPUT_ERROR

  • This is thrown if the request to a default API has bad input. The middleware automatically returns an http response with status code 400.

• UNAUTHORISED

  • When using the SuperTokens middleware, this error will automatically be handled. The middleware will automatically clear auth cookies.

  • This behavior can be overridden by supplying a custom error handler when initializing the Session Recipe in your backend code.

  • Nodejs code

    • Interface

    onUnauthorised:(message: string, request: Request, response: Response, next: NextFunction): void;
    
    

    • Example code

    let SuperTokens = require("supertokens-node");
    let Session = require("supertokens-node/recipe/session");
    
    SuperTokens.init({
        supertokens: {...},
        appInfo: {...},
        recipeList: [
            Session.init({
                errorHandlers: {
                    onUnauthorised?: (message, reqest, response, next) => {
                        // your custom code
                    },
                }
            })
        ]
    });
    

• TOKEN_THEFT_DETECTED

  • When using the SuperTokens middleware, this error will automatically be handled. The middleware will automatically revoke the session and reply with a session expired status code response with an error message "token theft detected".

  • This behavior can be overridden by supplying a custom error handler when initializing the Session Recipe in your backend code.

  • Nodejs code

    • Interface

    onTokenTheftDetected:(sessionHandle: string, userId: string, request: Request, response: Response, next: NextFunction): void;
    
    

    • Example Code

    let SuperTokens = require("supertokens-node");
    let Session = require("supertokens-node/recipe/session");
    
    SuperTokens.init({
        supertokens: {...},
        appInfo: {...},
        recipeList: [
            Session.init({
                errorHandlers: {
                    onTokenTheftDetected?: (sessionHandle, userId, req, res, next) => {
                        // your custom code
                    },
                }
            })
        ]
    });
    

• TRY_REFRESH_TOKEN

  • This error is thrown when the access token has expired, and to maintain the session, we must call the refresh API with the refresh session.
  • The refreshing happens automatically via our frontend SDK.