// Errors

Every error from Session kit's own logic is an AuthError, whether a method throws it, rejects with it, or publishes it in state.error. This page lists the codes, shows how to turn them into messages for your users, and covers the two storage failures you need to handle.

Error codesCopy Anchor Link

Match on an error's code, not its message, which may change in any release:

See Error codes for each code in full.

Show errors to usersCopy Anchor Link

An error's cause holds whatever failed underneath, such as the error your refresh callback threw. To keep messages out of your components, map codes to your own wording:

import { AuthError, type AuthErrorCode } from "@monarcode/session-kit";

const messages: Partial<Record<AuthErrorCode, string>> = {
  REFRESH_FAILED: "We can't reach the server. Check your connection.",
  PERSISTENCE_FAILED: "We couldn't save or clear your session.",
  UNAUTHENTICATED: "Sign in to continue.",
};

export function errorMessage(error: unknown): string {
  if (error instanceof AuthError) return messages[error.code] ?? error.message;
  return error instanceof Error ? error.message : "Something went wrong";
}

authFetch lets the failures of fetch and Request, such as a network error, through unchanged. They aren't AuthErrors, so errorMessage shows their own message.

Handle storage failuresCopy Anchor Link

Two storage failures need a decision from you:

• Storage can't be written. The client ends the session and publishes the error. That way, no one stays signed in to a session that would vanish on reload.
• Storage can't be cleared. Sign-out still takes effect in this tab, but signOut() rejects and state.error keeps the error. The saved credentials could restore the session on reload, so call signOut() again once storage works.