Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.discovr.media/llms.txt

Use this file to discover all available pages before exploring further.

SDK recovers from most authentication errors automatically. This guide helps you handle the exceptions and show appropriate messages to users. Typical entry points: signInWithPopup(), signInWithWebAuth(), signInWithDeviceCode(), then selectProfile() and API calls such as createPage().

​
When sign-in fails

try {
	await client.signInWithPopup();
	// If successful, continue to selectProfile()
} catch (err) {
	if (err.code === "USER_CANCELLED") {
		// User closed popup voluntarily
		console.log("User closed login window");
		// Don't show error—user made choice
	} else if (err.code === "NETWORK_ERROR") {
		// Network timeout or connectivity issue
		console.log("Network error. Check your connection and try again.");
		// Show user: retry button
	} else if (err.code === "AUTH_FAILED") {
		// Invalid credentials or auth server error
		console.log("Sign-in failed. Try again.");
		// Show user: retry button or "Try again"
	} else {
		// Unexpected error
		console.log("Unexpected error:", err.message);
		// Show user: "Something went wrong. Try again."
	}
}
What to do:
  • User cancelled: Don’t show error. User made a choice.
  • Network error: Show retry button. Prompt: “Check your connection and try again.”
  • Invalid credentials: Show error. Prompt: “Email or password incorrect. Try again.”
  • Other errors: Show generic message. Prompt: “Sign-in failed. Try again.”

​
When API calls fail

The same client is used after sign-in—for example createPage()—and errors below can surface on any session-scoped request. 
try {
	const page = await client.createPage();
	// Use page normally
} catch (err) {
	if (err.code === "TOKEN_INVALID" || err.code === "TOKEN_EXPIRED") {
		// User session ended
		console.log("Your session has expired. Please sign in again.");
		// Show: sign-in button or redirect to sign-in page
		await showSignInUI();
	} else if (err.code === "SESSION_EXPIRED") {
		// Page snapshot from older session
		console.log("Page session expired. Refreshing...");
		// SDK usually recovers automatically
		// If persists: "Please refresh the page."
	} else if (err.code === "WRONG_TOKEN_KIND") {
		// SDK internal error (shouldn't happen)
		console.log("Internal error. Refresh page and try again.");
		// Contact support if persists
	} else if (err.code === "NETWORK_ERROR") {
		// Network timeout
		console.log("Network error. Check connection and retry.");
		// Show: retry button
	} else {
		// Other API error
		console.log("Error:", err.message);
		// Show: generic error message
	}
}
Error mapping:
Error CodeMeaningWhat to show user
TOKEN_INVALIDMalformed auth header or missing token”Session invalid. Please sign in again.”
TOKEN_EXPIREDSession or refresh token expired”Session expired. Please sign in again.”
SESSION_EXPIREDPage was created in older session (e.g., opened in different tab/device)“Page session expired. Please refresh.” (SDK usually handles)
WRONG_TOKEN_KINDSent session token to identity endpoint (or vice versa)—SDK bug”Internal error. Refresh page.” (Report if persists)
NETWORK_ERRORNetwork timeout, DNS failure, or connectivity issue”Network error. Check your connection and try again.”
Network 401/403Authorization failed”Session invalid. Please sign in again.”
Other errorsServer error, validation error, or unexpected”Something went wrong. Try again.” (Include error ID for support)

​
SDK error recovery

SDK automatically handles:
  • Token refresh: Before token expires, SDK mints a fresh one. Transparent to your code.
  • Retry logic: If token expires mid-request, SDK refreshes and retries. You see no errors.
  • Snapshot recovery: If page session expires, SDK recovers using stored page filters. Usually transparent.
You mainly need to catch:
  • Sign-in failures (network, cancelled, auth failure)
  • Persistent token errors (token truly invalid/revoked)
  • Network errors (timeout, connectivity)
Most errors are handled automatically. You primarily need to handle sign-in failures and persistent authentication errors.

​
Error handling best practices

Do:
  • Show user-friendly messages (“Sign-in failed. Try again.”)
  • Provide retry buttons for network errors
  • Log errors for debugging (but never log tokens)
  • Handle offline gracefully
Don’t:
  • Show technical error messages to users (“TOKEN_EXPIRED_INVALID_SIGNATURE”)
  • Log or expose tokens
  • Retry indefinitely without backoff
  • Assume error codes—check for multiple possible codes (e.g., both TOKEN_INVALID and TOKEN_EXPIRED)
signInWithPopup · signInWithWebAuth · signInWithDeviceCode · selectProfile · createPage
Next: Learn security best practices