API

OkapiError

A core class that extends the native Error class with useful information and built-in functions.

• Type:

  readonly kind: OkapiErrorKind<TCustomKind>
  readonly source: OkapiErrorSource
  readonly statusCode?: number
  readonly statusText?: string
  readonly validationErrors?: TValidationErrors
  readonly raw?: unknown

• kind: the specific error category
• source: where the error originated
• statusCode: HTTP status code
• statusText: HTTP status text
• validationErrors: parsed validation details; see Custom Validation Errors
• raw: the original API or HTTP response body
• rawMessage: the original message from a recognized API response
• cause: the original thrown value
• isNetworkError: a getter that checks if an error is a network error
• isValidationError: a getter that checks if an error is a validation error

source

Identifies where the error originated. Compare it with the values from OKAPI_ERROR_SOURCE.

Constant	Value	Meaning
API	api	Recognized API error response
HTTP	http	HTTP response without a recognized API error body
NETWORK	network	Request failed or was aborted
UNEXPECTED	unexpected	Unrecognized thrown value
CUSTOM	custom	OkapiError created directly by the application

const OKAPI_ERROR_SOURCE = {
  API: 'api',
  HTTP: 'http',
  NETWORK: 'network',
  UNEXPECTED: 'unexpected',
  CUSTOM: 'custom',
} as const

import { OKAPI_ERROR_SOURCE } from '@alexovn/okapi'

if (error.source === OKAPI_ERROR_SOURCE.NETWORK) {
  showOfflineState()
}

constructor

Creates an OkapiError directly from an error kind, message, and optional error details.

• Type:

new OkapiError<
  TCustomKind extends string = never,
  TValidationErrors = ApiValidationErrors,
>(
  params: OkapiErrorParams<TCustomKind, TValidationErrors>,
): OkapiError<TCustomKind, TValidationErrors>

rawMessage

A getter for getting raw error message.

• Type:

(getter) OkapiError<
  TCustomKind extends string = never,
  TValidationErrors = ApiValidationErrors
>.rawMessage: string | undefined

isNetworkError

A getter that checks if an error is a network error.

• Type:

(getter) OkapiError<
  TCustomKind extends string = never,
  TValidationErrors = ApiValidationErrors
>.isNetworkError: boolean

isValidationError

A getter that checks if an error is a validation error.

• Type:

(getter) OkapiError<
  TCustomKind extends string = never,
  TValidationErrors = ApiValidationErrors
>.isValidationError: boolean

getApiResponseError

Creates an API-sourced error from a recognized API error response. Validation errors are read from raw.errors.

• Type:

OkapiError.getApiResponseError<
  TCustomKind extends string = never,
  TValidationErrors = ApiValidationErrors,
>(
  raw: ApiErrorResponse<TValidationErrors>,
  statusCode?: number,
  statusText?: string,
  options?: OkapiErrorOptions<TCustomKind, TValidationErrors>,
): OkapiError<TCustomKind, TValidationErrors>

getHttpResponseError

Creates an HTTP-sourced error from a status code when the response body is not a recognized API error response.

• Type:

OkapiError.getHttpResponseError<
  TCustomKind extends string = never,
  TValidationErrors = ApiValidationErrors,
>(
  statusCode: number,
  statusText?: string,
  raw?: unknown,
  options?: OkapiErrorOptions<TCustomKind, TValidationErrors>,
): OkapiError<TCustomKind, TValidationErrors>

getNetworkError

Creates a network-sourced error from a thrown value. Errors named AbortError use the abort kind; other values use the network kind by default.

• Type:

OkapiError.getNetworkError<
  TCustomKind extends string = never,
  TValidationErrors = ApiValidationErrors,
>(
  error: unknown,
  options?: OkapiErrorOptions<TCustomKind, TValidationErrors>,
): OkapiError<TCustomKind, TValidationErrors>

getUnexpectedError

Creates an unexpected-sourced error from an unrecognized thrown value.

• Type:

OkapiError.getUnexpectedError<
  TCustomKind extends string = never,
  TValidationErrors = ApiValidationErrors,
>(
  error: unknown,
  options?: OkapiErrorOptions<TCustomKind, TValidationErrors>,
): OkapiError<TCustomKind, TValidationErrors>

createApiErrorFromResponse

Creates an OkapiError from an HTTP response. A response body with a string message and either no validation payload or recognized validation errors becomes an API-sourced error; otherwise, it becomes an HTTP-sourced error. Use parseValidationErrors for custom validation-error shapes.

• Type:

function createApiErrorFromResponse<
  TCustomKind extends string = never,
  TValidationErrors = ApiValidationErrors,
>(
  response: ApiErrorResponseLike,
  options?: OkapiErrorOptions<TCustomKind, TValidationErrors>,
): OkapiError<TCustomKind, TValidationErrors>

mapOkapiError

Normalizes an unknown error and maps it to a presentation-friendly object containing a type, title, message, and the normalized OkapiError. Validation errors are also exposed as errors, including custom validation-error shapes.

• Type:

function mapOkapiError<
  TCustomKind extends string = never,
  TValidationErrors = ApiValidationErrors,
>(
  error: unknown,
  options?: MapOkapiErrorOptions<TCustomKind, TValidationErrors>,
): MappedOkapiError<TCustomKind, TValidationErrors>

normalizeOkapiError

Converts an unknown thrown value to an OkapiError. Existing OkapiError instances are returned unchanged, abort errors become network-sourced errors, and all other values become unexpected errors.

• Type:

function normalizeOkapiError<
  TCustomKind extends string = never,
  TValidationErrors = ApiValidationErrors,
>(
  error: unknown,
  options?: OkapiErrorOptions<TCustomKind, TValidationErrors>,
): OkapiError<TCustomKind, TValidationErrors>