---
url: /api.md
description: >-
  Explore the Okapi API for creating, classifying, and mapping errors, including
  OkapiError properties and core error-handling functions
---

# API

## `OkapiError`

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

* Type:

```ts
  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](/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 |

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

```ts
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:

```ts
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:

```ts
(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:

```ts
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:

```ts
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:

```ts
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:

```ts
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:

```ts
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:

```ts
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:

```ts
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](/custom-validation-errors).

* Type:

```ts
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](/custom-validation-errors).

* Type:

```ts
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:

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