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

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
TRANSPORT	transport	Request transport failure, cancellation, or timeout
UNEXPECTED	unexpected	Unrecognized thrown value
CUSTOM	custom	OkapiError created directly by the application

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

import { OKAPI_ERROR_SOURCE } from '@alexovn/okapi'

if (error.source === OKAPI_ERROR_SOURCE.TRANSPORT) {
  handleRequestFailure(error.kind)
}

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

Returns the original message from an API-sourced error response, if its raw body contains a string message. Returns undefined for other sources.

• Type:

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

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 transport-sourced error with the network kind by default.

• Type:

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

getAbortError

Creates a transport-sourced error with the abort kind by default.

• Type:

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

getTimeoutError

Creates a transport-sourced error with the timeout kind by default.

• Type:

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

getTransportError

Classifies a thrown value as abort when its name is AbortError, timeout when its name is TimeoutError, or network otherwise. The optional flags let adapters classify wrapped errors. Abort takes precedence when both flags are true. The resulting source is transport.

• Type:

OkapiError.getTransportError<
  TCustomKind extends string = never,
  TValidationErrors = ApiValidationErrors,
>(
  error: unknown,
  options?: OkapiErrorOptions<TCustomKind, TValidationErrors>,
  meta?: { isAbortError?: boolean; isTimeoutError?: boolean },
): 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>

createOkapiErrorFromResponse

Creates an OkapiError from an HTTP response. A response body with a string message becomes an API-sourced error. When it contains an errors property, Okapi parses it with parseValidationErrors; if parsing returns undefined, the error remains API-sourced but has no parsed validation errors. Bodies without a string message become HTTP-sourced errors. Use parseValidationErrors for custom validation-error shapes.

• Type:

function createOkapiErrorFromResponse<
  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. Values named AbortError or TimeoutError become transport-sourced errors with the corresponding kind; other values become unexpected errors. Optional flags support wrapped errors.

• Type:

function normalizeOkapiError<
  TCustomKind extends string = never,
  TValidationErrors = ApiValidationErrors,
>(
  error: unknown,
  options?: OkapiErrorOptions<TCustomKind, TValidationErrors>,
  meta?: { isAbortError?: boolean; isTimeoutError?: boolean },
): OkapiError<TCustomKind, TValidationErrors>