---
url: https://game-engine-io.github.io/enginex-frontend-sdk/concepts/error-codes.md
---
# Error codes

Reference for every `code` an `EnginexError` can carry: the gateway's
(`GATEWAY_ERROR_CODES`) and those the SDK itself generates without an HTTP response (`SDK_ERROR_CODES`). See
[Errors](/concepts/errors) for the full format of `EnginexError` and how to handle it.

About casing: most gateway codes are `SCREAMING_SNAKE_CASE`, but some newer
endpoints (`lookupCpf`) mirror the gateway in lowercase `snake_case` (e.g. `captcha_required`). The SDK
never normalizes the casing of `code` — treat the string exactly as the table shows it.

`ABORTED` appears in both lists (`GATEWAY_ERROR_CODES` and `SDK_ERROR_CODES`): the `status` tells you who
generated it. **`status: 0`** is the SDK — the app itself canceled the request via `signal`, and it can normally be
ignored; **a status other than `0`** is the gateway, responding with an `ABORTED` business error
(transaction aborted on the server), not a cancellation.

```ts
if (isEnginexError(e, 'ABORTED') && e.status === 0) return // canceled by the app: ignore
```

`details` comes raw from the gateway (keys as they came over the wire, no camelCase) and is `unknown` by default.
Only the codes with `details` documented below have an entry in `ErrorDetailsMap` — for those,
`isEnginexError(e, code)` narrows `e.details` automatically (see
[typed `details`](/concepts/errors#typed-details)); for the rest, do your own check
before using the content.

## Protocol generics {#protocol-generics}

With no specific business code, the gateway falls back to one of these based on the HTTP status.

| Code | Typical status | Meaning | Methods that throw |
|---|---|---|---|
| `UNKNOWN` | any | Status with no known mapping, or an error the SDK does not recognize (e.g. `EnginexError.from` with a value without `code`/`message`). With a 2xx `status`: unconfirmed operation, re-read the state before trying again ([Compliance errors](/concepts/compliance-errors#unconfirmed-operation)). | any method; 2xx on `kyc.uploadDocument` and `loyalty.redeem` |
| `INTERNAL_ERROR` | 500 | Internal gateway error. | any method |
| `INVALID_ARGUMENT` | 400/422 or 0 | Invalid parameters in the request. With `status: 0`, the SDK itself refused **before sending**: an id of `.` or `..` in the path (e.g. `deposits.get({ depositId: '..' })`), which the URL would normalize to another route. | `register`, `resetPassword`, `verifyPhone`, `confirmPhoneChange`, `config.get`, methods with an id in the path, others |
| `NOT_FOUND` | 404 | Resource not found. | any method |
| `ALREADY_EXISTS` | 409 | Resource already exists (conflict). | any method |
| `PERMISSION_DENIED` | 403 | No permission for the resource. | any method |
| `UNAUTHENTICATED` | 401 | No valid session; also thrown by the SDK itself **before sending** (without calling the network) when an `auth: 'required'` method is called without a session. | `changePassword`, `requestPhoneChange`, `confirmPhoneChange`, `enable2fa`, `verify2fa`, `disable2fa`, others with a required session |
| `RESOURCE_EXHAUSTED` | 429 | Usage limit reached. | `resendPhoneVerification`, others with a rate limit |
| `FAILED_PRECONDITION` | 412/422 | Server precondition not satisfied. | any method |
| `ABORTED` | 0 or an HTTP status | Cancellation: with `status: 0`, the app itself canceled the request via `signal` (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. | any method (SDK, via `signal`), or the gateway |
| `UNAVAILABLE` | 502/503/504 | Gateway or dependency is down. | any method |

## Authentication and account

| Code | Typical status | Meaning | Methods that throw |
|---|---|---|---|
| `INVALID_CREDENTIALS` | 401 | Incorrect email/CPF or password. | `login`, `changePassword`, `disable2fa` |
| `ACCOUNT_LOCKED` | 403 | Account temporarily locked (e.g. too many attempts). | `login` |
| `ACCOUNT_SUSPENDED` | 403 | Account suspended by the operator. | `login` |
| `ACCOUNT_BLOCKED` | 403 | Account permanently blocked. | `login` |
| `TOKEN_EXPIRED` | 401 | Access token expired; the SDK tries to renew it via automatic refresh before passing this on to the app. | authenticated requests (rarely reaches the app) |
| `TOKEN_INVALID` | 401 | Malformed or revoked token; includes the `resetPassword`/`verifyEmail` token. | `resetPassword`, `verifyEmail`, authenticated requests |
| `SESSION_EXPIRED` | 401 | Session expired on the gateway (refresh token also invalid). | authenticated requests |
| `2FA_REQUIRED` | 428 | Login requires the code from the authenticator app; the SDK never passes this on as a rejection — `login` returns `{ status: '2fa_required' }`. | handled internally by `login` |
| `2FA_INVALID` | 422 | Incorrect or expired 2FA code. | `login`, `verify2fa`, `disable2fa` |

## Sign-up and verification

| Code | Typical status | Meaning | Methods that throw |
|---|---|---|---|
| `USER_NOT_FOUND` | 404 | User not found. | any method with `userId` |
| `EMAIL_ALREADY_EXISTS` | 409 | Email already registered. | `register` |
| `CPF_ALREADY_EXISTS` | 409 | CPF already registered. | `register` |
| `INVALID_CPF` | 422 | Invalid CPF (check digit). | `register` |
| `INVALID_EMAIL` | 422 | Invalid email. | `register` |
| `INVALID_PHONE` | 422 | Invalid phone number. | `register`, `requestPhoneChange` |
| `PASSWORD_EXPIRED` | 403 | Password expired; ask for a change before continuing. | `login` |
| `PASSWORD_SAME_AS_CURRENT` | 422 | New password is the same as the current one. | `changePassword` |

## CPF and captcha (mixed case, mirrors the gateway)

These four come in lowercase `snake_case` — they are not `SCREAMING_SNAKE_CASE` like the rest of the list.

| Code | Typical status | Meaning | `details` | Methods that throw |
|---|---|---|---|---|
| `captcha_required` | 428 | Captcha required before repeating the call. | `{ site_key: string }` (or absent) — typed in `ErrorDetailsMap` as `CaptchaRequiredDetails \| undefined` | `lookupCpf` |
| `rate_limited` | 429 | Limit of calls to the Receita (Brazilian tax authority) reached. | raw | `lookupCpf` |
| `cpf_already_registered` | 409 | CPF already has an account. | raw | `lookupCpf` |
| `cpf_validation_failed` | 422 | CPF invalid or not found at the Receita. | raw | `lookupCpf` |

## Financial and payments {#financial-and-payments}

Passed through by the gateway from the payment/wallet service. The status is what the gateway's `handleAppError`
assigns: codes without their own category there come out as **500**, even though they are business errors —
handle them by `code`, never by status. The minimum/maximum deposit and withdrawal limits from the config do **not**
use these codes: the gateway refuses them earlier, with `INVALID_ARGUMENT` (400) and a ready-made message
(e.g. `depósito mínimo é 10.00 BRL`).

| Code | Typical status | Meaning | Methods that throw |
|---|---|---|---|
| `INSUFFICIENT_BALANCE` | 422 | Insufficient balance for the operation. | `withdrawals.request` (no OTP), `withdrawals.confirmOtp` |
| `KYC_REQUIRED` | 422 | Identity verification pending to move money. | `deposits.createPix`, `withdrawals.request`, `withdrawals.confirmOtp` |
| `WITHDRAWAL_LIMIT_EXCEEDED` | 429 | Withdrawal limit (responsible gaming/operator) exceeded. | `withdrawals.request` (no OTP), `withdrawals.confirmOtp` |
| `DEPOSIT_LIMIT_EXCEEDED` | 429 | Deposit limit (responsible gaming/operator) exceeded. | `deposits.createPix` |
| `WITHDRAWAL_PENDING` | 500 | A withdrawal is already pending. | `withdrawals.request` (no OTP), `withdrawals.confirmOtp` |
| `PAYMENT_FAILED` | 500 | Payment refused by the provider. | `deposits.createPix`, `withdrawals.request`, `withdrawals.confirmOtp` |
| `PAYMENT_EXPIRED` | 500 | Payment window expired (e.g. PIX). | payment methods |
| `PAYMENT_CANCELLED` | 500 | Payment canceled by the player or the provider. | payment methods |
| `RESERVATION_NOT_FOUND` | 500 | Balance reservation not found (expired or already confirmed). | products (bets, casino) |
| `RESERVATION_EXPIRED` | 500 | Balance reservation expired before confirmation. | products (bets, casino) |
| `DUPLICATE_TRANSACTION` | 500 | Duplicate transaction in the wallet service. | methods that move money |
| `TRANSACTION_FAILED` | 500 | Transaction failed in the wallet service. | methods that move money |

## Idempotency

Emitted by the gateway's idempotency middleware on the routes that move money
(`deposits.createPix`, `withdrawals.request`, `withdrawals.confirmOtp`, and the product ones). See
[Idempotency](/concepts/idempotency).

| Code | Typical status | Meaning | What to do |
|---|---|---|---|
| `KEY_IN_USE` | 409 | The same `Idempotency-Key` is still being processed (another tab, double click). | Wait and repeat with the **same** key: you get the first one's response. |
| `PAYLOAD_MISMATCH` | 422 | The key was already used with another body (another amount, another PIX key). | App bug: generate a new key per operation. |
| `INVALID_KEY` | 400 | Key longer than 255 characters. | Use a UUID (`crypto.randomUUID()`). |

## Sports betting

| Code | Typical status | Meaning |
|---|---|---|
| `BET_NOT_FOUND` | 404 | Bet not found. |
| `BET_CLOSED` | 422 | Market closed for the bet. |
| `ODDS_CHANGED` | 409 | Odds changed between the quote and the confirmation. |
| `CASHOUT_UNAVAILABLE` | 422 | Cashout unavailable for this bet. |
| `BET_LIMIT_EXCEEDED` | 422 | Operator bet limit exceeded. |

No SDK method throws these today: the sportsbook (FIRST) runs in its own frame (see
[Sportsbook (FIRST)](/igaming/sportsbook)). They are listed because the gateway defines them.

## Casino

Thrown by `igaming.casino` ([Casino and launching a game](/igaming/casino#errors)). The gateway does not map
every code to a status of its own: decide by `code`.

| Code | Typical status | Meaning | Methods that throw |
|---|---|---|---|
| `GAME_NOT_FOUND` | 404 | Game not found in the catalog. | `casino.getGame`, `casino.launchGame` |
| `SESSION_NOT_FOUND` | 404 | Game session (at the provider) not found. | casino session methods |
| `PROVIDER_ERROR` | 503 | Error at the casino provider: treat as unavailable. | catalog and `casino.launchGame` |
| `CASINO_UNAVAILABLE` | 500 | Casino unavailable (provider or operator): treat as unavailable. | catalog and `casino.launchGame` |

`casino.launchGame` also throws `SELF_EXCLUDED` and `COOLING_OFF` (see
[Compliance and responsible gaming](#compliance-and-responsible-gaming)).

## Bonuses

Thrown by `igaming.bonus` ([Bonuses and promo codes](/igaming/bonus#errors)).

| Code | Typical status | Meaning | Methods that throw |
|---|---|---|---|
| `BONUS_NOT_FOUND` | 404 | Campaign, participation or promo code does not exist (or belongs to another player). | `bonus.getOffer`, `bonus.optIn`, `bonus.claim`, `bonus.resolvePromoCode`, `bonus.redeemPromoCode` |
| `BONUS_EXPIRED` | 500 | Outside the joining or redemption window. The gateway does not map it yet: decide by `code`. | `bonus.optIn`, `bonus.claim`, promo codes |
| `BONUS_NOT_ELIGIBLE` | 500 | The player cannot join or redeem (e.g. has not qualified yet). The gateway does not map it yet: decide by `code`. | `bonus.optIn`, `bonus.claim`, promo codes |
| `BONUS_ALREADY_CLAIMED` | 409 | Reward already redeemed; promo code already used. | `bonus.optIn`, `bonus.claim`, `bonus.redeemPromoCode` |

## Predictions

Thrown by `@getenginex/sdk-predictions`. The gateway does not map these codes to a status of their own yet:
they arrive with **HTTP 500**. Always decide by `code` ([Orders](/predictions/orders#errors)).

| Code | Typical status | Meaning | Methods that throw |
|---|---|---|---|
| `EVENT_NOT_FOUND` | 500 | Event not found. | `markets.getEvent` |
| `MARKET_NOT_FOUND` | 500 | Market not found. | `markets.getMarket` and the market reads, `orders.place`, `comments.list`, `comments.create` |
| `MARKET_NOT_OPEN` | 500 | The market has not opened yet or has already closed. | `orders.place`, `orders.placeBatch` |
| `NO_LIQUIDITY` | 500 | No liquidity to match the order. | `orders.place`, `orders.placeBatch` |
| `ORDER_NOT_FOUND` | 500 | Order not found (or belongs to another player). | `orders.get`, `orders.cancel`, `orders.amend` |
| `COMMENT_NOT_FOUND` | 500 | Comment not found. | `comments.like`, `comments.unlike` |

`orders.place` also throws `INSUFFICIENT_BALANCE` (see [Financial and payments](#financial-and-payments)).

## Compliance and responsible gaming {#compliance-and-responsible-gaming}

| Code | Typical status | Meaning | Methods that throw |
|---|---|---|---|
| `KYC_REQUIRED` | 422 | Identity verification (KYC) pending before the operation. | withdrawal/deposit endpoints (outside this SDK) |
| `KYC_PENDING` | 422 | KYC submitted and under review. | same |
| `KYC_REJECTED` | 500 | KYC rejected. The gateway's `handleAppError` does not map it either: it arrives as HTTP 500 with the `code` preserved. | same |
| `SELF_EXCLUDED` | 422 | Player is self-excluded. | `login`, `casino.launchGame` |
| `COOLING_OFF` | 500 | Player is in a cooling-off period. The gateway's `handleAppError` does not map this code: it arrives as HTTP 500 with the `code` preserved. | launching a game (casino); decide by `code` |

## SDK codes (no HTTP response from the gateway)

`status` is always `0` for these — there was no HTTP response.

| Code | Meaning |
|---|---|
| `NETWORK_ERROR` | Network failure (`fetch` rejected): DNS, connection refused, CORS blocked, offline. |
| `TIMEOUT` | The request did not respond within `timeoutMs`. |
| `ABORTED` | The app itself canceled the request via `signal` (`AbortController`). Same code the gateway can emit with an HTTP status — see the table [Protocol generics](#protocol-generics). |
| `VALIDATION_ERROR` | Gateway response outside the expected schema, in `'strict'` mode (or, in `'warn'`, with the root itself outside the format; see [Response validation](/concepts/validation)); or a 2xx response that passed the schema but failed a post-response check (e.g. a `login` without 2FA that came back without tokens). |
| `CONFIGURATION_ERROR` | Incomplete or missing client configuration: `baseUrl`/`tenantHost`/`fetch` not resolved (see [Next.js / SSR](/guide/getting-started)); or the client was disposed with `client.dispose()`. |

## New codes the SDK does not know yet

`EnginexErrorCode` accepts any string (`KnownErrorCode | (string & {})`), so `isEnginexError`
also works for new codes the gateway may emit before the SDK knows them — the
autocomplete suggests the codes above, but does not prevent others.
