Addresses every actionable item from docs/DOCUMENTATION-REVIEW-2026-03-01.md:
DOC-CRIT-1: README.md — expanded from one line to full project README
- Prerequisites, quick start, command table, env vars, directory overview,
tech stack summary, links to CLAUDE.md and all docs
DOC-CRIT-3: docs/STATE-MANAGEMENT.md — decision guide for all state containers
- Decision matrix table; TanStack Query, React Hook Form, URL params,
localStorage (with actual key names), QContext, useState/useReducer — each
with scope rules, code examples, and what NOT to put there
DOC-SIG-1: docs/COMPONENT-PATTERNS.md — five architectural patterns
- Metadata-driven rendering, data-qqq-id convention, useAsyncCombobox,
widget rendering pipeline, field adornment priority — all grounded in
actual source code with examples
DOC-SIG-2: docs/TYPE-GLOSSARY.md — ~45 types across 6 domain sections
- App/Auth, Metadata, Records/Queries, Processes, Widgets, Enums
- Key-field descriptions, usage examples, import cheat sheet
DOC-SIG-3: docs/API-ERROR-HANDLING.md — error handling architecture
- 401 interceptor, global query/mutation handler, status-by-status guide
(400→form fields, 403→hide/toast, 404→empty state, 5xx→toast+retry),
when to add per-query handling, retry back-off, complete form example
DOC-SIG-4: zod-from-metadata.ts — @example added to zodFieldFromMetadata
- Shows STRING required+maxLength and INTEGER optional+bounds examples
DOC-SIG-5: docs/FORM-VALIDATION.md — end-to-end validation strategy
- Schema generation, field-type→Zod mapping table, required vs optional,
number bounds, default values, client vs server validation, custom
refinements, DynamicFormField dispatch, complete worked example
DOC-MIN-3: docs/ACCESSIBILITY.md — WCAG 2.1 AA reference
- All implemented items, CSS media queries, testing guide, new-component
checklist, outstanding items
552/552 tests pass; 0 TypeScript errors
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
11 KiB
API Error Handling Guide
This document describes how API errors flow through the QQQ Frontend Next application and what, if anything, individual components need to do about them.
The short answer is: most errors require no per-call handling. The global error handler in the query client toasts an appropriate message automatically, and the 401 interceptor in the Axios client redirects to login. Individual components only need to add their own handling when the generic behavior is insufficient for a specific UX requirement.
Architecture Overview
There are two independent error interception layers:
- Axios response interceptor (
src/lib/api/client.ts) — fires synchronously on every HTTP response before the promise settles. Handles 401 (unauthorized) only. - TanStack Query global handlers (
src/lib/query-client.ts) —QueryCache.onErrorfor reads,MutationCache.onErrorfor writes. Fire after the interceptor. Handle all other errors by toasting a message.
API response
│
▼
Axios interceptor
│ 401 → call unauthorizedCallback() → redirect to login
│ all others → pass through as rejected promise
▼
TanStack Query cache (onError)
│ 401 → silently ignored (already handled)
│ 403 → toast "Permission denied" / "You do not have permission…"
│ 404 → toast "Resource not found"
│ 5xx → toast "Server error — retrying…" / "Server error — please try again"
│ network → toast "Something went wrong"
▼
Component (optional per-query onError)
│ Only needed when generic toast is wrong for the specific UX
The 401 Interceptor
Location: src/lib/api/client.ts
The singleton APIClient registers a response interceptor that fires on every request:
this.client.interceptors.response.use(
(response) => response,
(error: AxiosError) => {
if (error.response?.status === 401 && this.unauthorizedCallback) {
this.unauthorizedCallback()
}
return Promise.reject(error) // always re-reject so TanStack Query also sees it
}
)
The unauthorizedCallback is wired to the auth provider's logout/redirect function during initialization. When a 401 arrives:
- The callback fires → clears auth state → redirects to the login page.
- The error is still re-rejected, so TanStack Query's
onErroralso fires. - The global handler in
query-client.tsexplicitly silences 401s to avoid a redundant toast on top of the redirect.
Implication for components: Never handle 401 in a component. The interceptor + auth provider handle it globally. Writing per-component 401 handling will race with the redirect and confuse users.
The Global Query Error Handler
Location: src/lib/query-client.ts — handleQueryError function
function handleQueryError(error: unknown, context: 'query' | 'mutation'): void {
const status = getErrorStatusCode(error)
if (status === 401) return // handled by axios interceptor
if (status === 403) {
toast.error(
context === 'mutation'
? 'You do not have permission to perform this action'
: 'Permission denied'
)
return
}
if (status === 404) {
toast.error('Resource not found')
return
}
if (status !== undefined && status >= 500) {
toast.error(
context === 'mutation'
? 'Server error — please try again'
: 'Server error — retrying…'
)
return
}
// Network failure or unexpected status
toast.error('Something went wrong')
}
This handler is registered on both QueryCache and MutationCache:
export const queryClient = new QueryClient({
queryCache: new QueryCache({
onError: (error) => handleQueryError(error, 'query'),
}),
mutationCache: new MutationCache({
onError: (error) => handleQueryError(error, 'mutation'),
}),
})
Implication for components: For most queries and mutations, you do not need onError at all. The global handler covers toasting. Add per-query handling only when you need to do something the global handler cannot — such as mapping a 400 error's field messages back to form fields.
Extracting the Status Code
Location: src/lib/utils/error-utils.ts
import { getErrorStatusCode } from '@/lib/utils/error-utils'
const status = getErrorStatusCode(error)
getErrorStatusCode handles two shapes:
AxiosError— readserror.response?.status- Plain objects with a numeric
statusproperty (e.g. fetch-based wrappers)
Returns undefined for anything else (non-object errors, null, network failures with no response).
Status-by-Status Guide
400 — Validation Error
The global handler does NOT toast on 400 because 400s typically carry field-level validation messages that must be mapped back to individual form fields. Handle 400 explicitly wherever you submit a form.
import { getErrorStatusCode } from '@/lib/utils/error-utils'
const mutation = useMutation({
mutationFn: (data: FieldValues) => saveRecord('order', data),
onError: (error) => {
if (getErrorStatusCode(error) === 400) {
// Map backend validation messages to React Hook Form fields
const fieldErrors = extractFieldErrors(error) // your helper
for (const [field, message] of Object.entries(fieldErrors)) {
form.setError(field, { type: 'server', message })
}
}
// Non-400 errors are already toasted by the global handler
},
})
If a 400 arrives outside of a form context, add a toast yourself:
onError: (error) => {
if (getErrorStatusCode(error) === 400) {
toast.error('Invalid request — please check your input')
}
}
403 — Permission Denied
The global handler toasts a generic permission-denied message. If the 403 should instead silently hide an action (e.g. a button that should not appear for users without permission), suppress the default behavior by checking permissions from metadata before rendering rather than relying on the API to reject:
// Preferred: hide the action before the user tries it
{tableMetaData.capabilities.includes('insert') && (
<Button onClick={openCreateModal}>New Record</Button>
)}
If you need custom handling on a 403, use onError and call toast yourself — or do nothing if the generic toast is acceptable.
404 — Not Found
The global handler toasts "Resource not found". For record-view pages where 404 means the record was deleted, render an empty state instead:
const { data: record, error } = useQuery({
queryKey: queryKeys.tableRecord(tableName, recordId),
queryFn: () => getRecord(tableName, recordId),
})
if (getErrorStatusCode(error) === 404) {
return <EmptyState message="This record no longer exists" />
}
The global handler will also toast, which is acceptable — the empty state just provides additional UI context.
5xx — Server Error
The global handler toasts "Server error — retrying…" for queries and "Server error — please try again" for mutations. Queries are automatically retried up to 3 times with exponential back-off (1 s → 2 s → 4 s, max 30 s) before the error surfaces.
No additional per-component handling is needed for 5xx unless you want a custom retry UI or a structured error state for a specific page.
Network Failure (no response)
Treated as non-4xx by the retry logic — queries retry up to 3 times. The global handler toasts "Something went wrong" after all retries are exhausted. No per-component handling needed for the common case.
When to Add Per-Query Error Handling
Add onError to a specific useQuery or useMutation call when:
| Scenario | What to do |
|---|---|
| 400 with field-level validation messages | Map errors to form fields with form.setError() |
| 403 should render empty state instead of toast | Catch 403, render empty UI, call toast yourself if the global one also fires |
| 404 should render a structured empty state page | Check getErrorStatusCode(error) === 404 and render <EmptyState> |
| Error should navigate away (e.g. deleted parent record) | useRouter().push('/...') in onError |
| The generic toast message is wrong for this specific action | Supply a custom onError that calls toast.error(customMessage) |
For all other cases, rely on the global handler and write no error-handling code in the component.
Retry Behavior
The smartRetry function in src/lib/query-client.ts controls when TanStack Query retries:
function smartRetry(failureCount: number, error: unknown): boolean {
const status = getErrorStatusCode(error)
// Never retry client errors — they are deterministic
if (status !== undefined && status >= 400 && status < 500) return false
// Retry server errors and network failures up to 3 times
return failureCount < 3
}
Back-off schedule: 1 s → 2 s → 4 s, capped at 30 s.
4xx errors are never retried. There is no per-component way to opt into retrying 4xx errors — that would be intentional since a 400 with bad field data will not resolve itself on retry.
Complete Example — Form with 400 Handling
'use client'
import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { toast } from 'sonner'
import { saveRecord } from '@/lib/api/tables'
import { queryKeys } from '@/lib/query-client'
import { getErrorStatusCode } from '@/lib/utils/error-utils'
export function EditOrderForm({ orderId, schema, defaultValues }: Props) {
const queryClient = useQueryClient()
const form = useForm({ resolver: zodResolver(schema), defaultValues })
const mutation = useMutation({
mutationFn: (data: FieldValues) => saveRecord('order', orderId, data),
onSuccess: () => {
// Invalidate so the record view refreshes
queryClient.invalidateQueries({ queryKey: queryKeys.tableRecord('order', orderId) })
toast.success('Order saved')
},
onError: (error) => {
if (getErrorStatusCode(error) === 400) {
// Map field errors from the server response body to form fields.
// The global handler does NOT toast on 400, so we must do it here or
// rely on inline field error messages in the form UI.
const body = (error as AxiosError<{ errors: Record<string, string> }>).response?.data
if (body?.errors) {
for (const [field, message] of Object.entries(body.errors)) {
form.setError(field, { type: 'server', message })
}
} else {
toast.error('Please correct the highlighted fields')
}
return
}
// 401, 403, 404, 5xx, network — already toasted by the global handler
},
})
return (
<form onSubmit={form.handleSubmit((data) => mutation.mutate(data))}>
{/* field components */}
</form>
)
}
Quick Reference
| Layer | File | Handles |
|---|---|---|
| Axios interceptor | src/lib/api/client.ts |
401 → redirect to login |
| Global query handler | src/lib/query-client.ts |
403, 404, 5xx, network → toast |
Per-component onError |
Your component | 400 field errors, custom empty states, navigation |
getErrorStatusCode |
src/lib/utils/error-utils.ts |
Normalize AxiosError and plain-object errors to HTTP status code |