Errors

FFDB surfaces errors across client initialization, auth/session, request execution, and sync. This reference shows what errors look like and how to handle them predictably.

Request options that affect error behavior

type ClientRequestOptions = RequestInit & {
  retries?: number
  retryDelay?: number
  retryOn?: number[]
  parse?: 'json' | 'text' | 'blob'
  useCache?: boolean
}

Defaults in the request helper:

retries = 3
retryDelay = 500
retryOn = [429, 500, 502, 503, 504]
exponential backoff based on retry attempt

Structured request error shape

HTTP failures are normalized to an Error with extra fields:

type RequestError = Error & {
  status?: number
  code?: string
  errors?: Array<{ field?: string; message: string }>
  fieldErrors?: Record<string, string>
  payload?: unknown
}

This makes it possible to show both high-level and field-level feedback.

End-to-end handling example

try {
  const data = await client.request<{ status: string }>('/api/some-endpoint', {
    method: 'POST',
    body: { name: 'Alice' },
    retries: 2,
    retryOn: [429, 500, 503],
  })

  console.log(data)
} catch (error) {
  const err = error as Error & {
    status?: number
    code?: string
    fieldErrors?: Record<string, string>
    payload?: unknown
  }

  console.error('Request failed', {
    message: err.message,
    status: err.status,
    code: err.code,
    fieldErrors: err.fieldErrors,
    payload: err.payload,
  })
}

Common error sources

Name
Initialization failures
Description
Startup health checks or connectivity issues can prevent client readiness.
Name
Unauthorized responses
Description
Session or key state may require refresh; unrecoverable auth clears local auth state.
Name
Offline transitions
Description
Network-like failures trigger offline mode and cached fallbacks where configured.
Name
Sync failures
Description
Exposed through sync.status.error and push results (failed count).
Name
Hook-level React errors
Description
useFFDB, useQuery, and related hooks surface error fields for UI handling.

Practical handling strategy

Handle initialization, request, and sync errors separately in UI.
Use status-aware messaging: unauthorized, offline, validation, and server errors should look different.
For forms, prefer fieldErrors when present.
For background sync issues, surface pending mutation counts and retry actions.

Do not collapse all failures into a generic message. Different failure classes imply different recovery actions.