---
url: https://game-engine-io.github.io/enginex-frontend-sdk/concepts/errors.md
---
# Errors

Every failure is an `EnginexError`:

| Field | Content |
|---|---|
| `code` | Gateway code (e.g. `INSUFFICIENT_BALANCE`) or SDK code (`NETWORK_ERROR`, `TIMEOUT`, `ABORTED`, `VALIDATION_ERROR`, `CONFIGURATION_ERROR`). |
| `status` | HTTP status; `0` when there was no HTTP response (network, timeout, cancellation, validation, configuration). Exception: the `UNAUTHENTICATED` that the SDK itself throws **before sending**, when there is no session, comes with `401`. |
| `message` | Message from the gateway or the SDK. |
| `details` | Raw map sent by the gateway, with the keys as they came over the wire (e.g. `site_key` in `captcha_required`), **without** conversion to camelCase. |
| `requestId` | Give it to support to trace the request. |
| `retryAfter` | Seconds until trying again (on 429). |

```ts
import { isEnginexError } from '@getenginex/sdk'

try {
  await enginex.auth.login({ email, password })
} catch (e) {
  if (isEnginexError(e, 'INVALID_CREDENTIALS')) return showError('Incorrect email or password')
  if (isEnginexError(e, 'ACCOUNT_LOCKED')) return showError('Account temporarily locked')
  if (isEnginexError(e, 'NETWORK_ERROR') || isEnginexError(e, 'TIMEOUT')) return showError('No connection')
  throw e
}
```

`ABORTED` with `status` `0` means the app itself canceled the request (via `signal`), so it
can normally be ignored. The gateway can also emit `ABORTED` with an HTTP status; in that case
it is a business error from the server, not a cancellation.

`isEnginexError` works even if the app has two copies of the package installed.

The full list of known codes, with typical status and the meaning of each, is in
[Error codes](/concepts/error-codes). The `EnginexErrorCode` type also accepts new codes
that the gateway may emit.

## Typed `details` {#typed-details}

By default `details` is `unknown` — the gateway's raw map, with no format guarantee. For the few
codes with a known format (e.g. `captcha_required`), `isEnginexError(e, code)` narrows
`details` automatically via `ErrorDetailsMap`:

```ts
if (isEnginexError(e, 'captcha_required')) {
  e.details?.site_key // string | undefined, no cast
}
```

The type of `captcha_required` is `CaptchaRequiredDetails | undefined`: the gateway may omit
`details`, so TypeScript requires the `?.` (and your code decides what to do without the site key).

To type the `details` of your own codes (e.g. an ad hoc code from your operator), extend
`ErrorDetailsMap` through declaration merging:

```ts
declare module '@getenginex/sdk' {
  interface ErrorDetailsMap {
    my_code: { field: string }
  }
}
```

## Serialization

`EnginexError` is serializable: `JSON.stringify(e)` uses `toJSON()` (`{ name, code, message, status,
details, requestId, retryAfter }`), useful for structured logs, Sentry, or sending the error through
`postMessage`/between a Web Worker and the page. To rebuild it on the other side, use
`EnginexError.from`:

```ts
const json = JSON.stringify(error)
// ...crosses a worker, a log, a queue...
const revived = EnginexError.from(JSON.parse(json))
isEnginexError(revived, 'INVALID_CREDENTIALS') // works as usual
```

`EnginexError.from` also accepts an `EnginexError` (returns the same object) or any other
value: without the `{ code, message }` shape, it becomes `UNKNOWN` with the best possible message.

`String(e)` returns `EnginexError [CODE]: message`, useful in plain-text logs.
