# Errors (https://session-kit.pages.dev/docs/configuration/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 shows
how to match on them, how to turn them into messages for your users, and the
storage failures you need to handle.

## Error codes

Match on an error's `code`, not its message, which may change in any
release. [Error codes](https://session-kit.pages.dev/docs/reference/error-codes) lists every code and what
it means.

## Show errors to users

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:

```ts title="src/error-message.ts"
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` passes on the failures of `fetch` and `Request`, such as a
network error, unchanged. With server rendering, the browser client's
`signIn` passes on what your sign-in function threw, unchanged too. These
usually aren't `AuthError`s, so `errorMessage` shows their own message.

## Handle storage failures

Three storage failures need a decision from you:

- **Storage can't be read.** `status` becomes `unavailable`, with the error
  in `state.error`. The saved session stays as it is, and the next
  `getSession()` or `retry()` reads it again.
- **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.