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 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.
if (isEnginexError(e, 'ABORTED') && e.status === 0) return // canceled by the app: ignoredetails 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); for the rest, do your own check before using the content.
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). | 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
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.
| 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)). They are listed because the gateway defines them.
Casino
Thrown by igaming.casino (Casino and launching a game). 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).
Bonuses
Thrown by igaming.bonus (Bonuses and promo codes).
| 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).
| 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).
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. |
VALIDATION_ERROR | Gateway response outside the expected schema, in 'strict' mode (or, in 'warn', with the root itself outside the format; see Response 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); 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.