Skip to main content

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#

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
},
}
})
]
});