# Frontend Error Handling

## Purpose

Frontend backend errors use a shared path:

1. `frontend/src/shared/api/httpClient.ts` parses failed HTTP responses.
2. `ApiError` preserves backend `message`, `code`, `details`, and HTTP `status`.
3. `AuthExpiredError` represents expired or invalid cookie sessions.
4. `frontend/src/shared/errors/errorMessages.ts` converts unknown errors into user-facing strings.

Views and business hooks should use `getErrorMessage` or `getOptionalErrorMessage` instead of reading `.message` directly.

## Rules

- Do not create local `getErrorMessage` helpers in feature components or hooks.
- Do not read `query.error.message` or `mutation.error.message` directly in JSX.
- Do not silently swallow backend failures or replace failed persisted workflows with fallback product data.
- Auth expiration should redirect through the auth session flow, not display raw backend errors.
- Runtime invariant errors, such as context hooks used outside providers, may still throw native `Error` instances.

## Verification

`frontend/src/shared/errors/errorMessages.test.ts` covers the formatter contract for `ApiError`, `AuthExpiredError`, regular `Error`, and unknown values.