This version (v0.7) has not been published to npm yet.
Skip to content

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.

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); 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.

CodeTypical statusMeaningMethods that throw
UNKNOWNanyStatus 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_ERROR500Internal gateway error.any method
INVALID_ARGUMENT400/422 or 0Invalid 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_FOUND404Resource not found.any method
ALREADY_EXISTS409Resource already exists (conflict).any method
PERMISSION_DENIED403No permission for the resource.any method
UNAUTHENTICATED401No 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_EXHAUSTED429Usage limit reached.resendPhoneVerification, others with a rate limit
FAILED_PRECONDITION412/422Server precondition not satisfied.any method
ABORTED0 or an HTTP statusCancellation: 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
UNAVAILABLE502/503/504Gateway or dependency is down.any method

Authentication and account ​

CodeTypical statusMeaningMethods that throw
INVALID_CREDENTIALS401Incorrect email/CPF or password.login, changePassword, disable2fa
ACCOUNT_LOCKED403Account temporarily locked (e.g. too many attempts).login
ACCOUNT_SUSPENDED403Account suspended by the operator.login
ACCOUNT_BLOCKED403Account permanently blocked.login
TOKEN_EXPIRED401Access 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_INVALID401Malformed or revoked token; includes the resetPassword/verifyEmail token.resetPassword, verifyEmail, authenticated requests
SESSION_EXPIRED401Session expired on the gateway (refresh token also invalid).authenticated requests
2FA_REQUIRED428Login 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_INVALID422Incorrect or expired 2FA code.login, verify2fa, disable2fa

Sign-up and verification ​

CodeTypical statusMeaningMethods that throw
USER_NOT_FOUND404User not found.any method with userId
EMAIL_ALREADY_EXISTS409Email already registered.register
CPF_ALREADY_EXISTS409CPF already registered.register
INVALID_CPF422Invalid CPF (check digit).register
INVALID_EMAIL422Invalid email.register
INVALID_PHONE422Invalid phone number.register, requestPhoneChange
PASSWORD_EXPIRED403Password expired; ask for a change before continuing.login
PASSWORD_SAME_AS_CURRENT422New 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.

CodeTypical statusMeaningdetailsMethods that throw
captcha_required428Captcha required before repeating the call.{ site_key: string } (or absent) — typed in ErrorDetailsMap as CaptchaRequiredDetails | undefinedlookupCpf
rate_limited429Limit of calls to the Receita (Brazilian tax authority) reached.rawlookupCpf
cpf_already_registered409CPF already has an account.rawlookupCpf
cpf_validation_failed422CPF invalid or not found at the Receita.rawlookupCpf

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).

CodeTypical statusMeaningMethods that throw
INSUFFICIENT_BALANCE422Insufficient balance for the operation.withdrawals.request (no OTP), withdrawals.confirmOtp
KYC_REQUIRED422Identity verification pending to move money.deposits.createPix, withdrawals.request, withdrawals.confirmOtp
WITHDRAWAL_LIMIT_EXCEEDED429Withdrawal limit (responsible gaming/operator) exceeded.withdrawals.request (no OTP), withdrawals.confirmOtp
DEPOSIT_LIMIT_EXCEEDED429Deposit limit (responsible gaming/operator) exceeded.deposits.createPix
WITHDRAWAL_PENDING500A withdrawal is already pending.withdrawals.request (no OTP), withdrawals.confirmOtp
PAYMENT_FAILED500Payment refused by the provider.deposits.createPix, withdrawals.request, withdrawals.confirmOtp
PAYMENT_EXPIRED500Payment window expired (e.g. PIX).payment methods
PAYMENT_CANCELLED500Payment canceled by the player or the provider.payment methods
RESERVATION_NOT_FOUND500Balance reservation not found (expired or already confirmed).products (bets, casino)
RESERVATION_EXPIRED500Balance reservation expired before confirmation.products (bets, casino)
DUPLICATE_TRANSACTION500Duplicate transaction in the wallet service.methods that move money
TRANSACTION_FAILED500Transaction 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.

CodeTypical statusMeaningWhat to do
KEY_IN_USE409The 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_MISMATCH422The key was already used with another body (another amount, another PIX key).App bug: generate a new key per operation.
INVALID_KEY400Key longer than 255 characters.Use a UUID (crypto.randomUUID()).

Sports betting ​

CodeTypical statusMeaning
BET_NOT_FOUND404Bet not found.
BET_CLOSED422Market closed for the bet.
ODDS_CHANGED409Odds changed between the quote and the confirmation.
CASHOUT_UNAVAILABLE422Cashout unavailable for this bet.
BET_LIMIT_EXCEEDED422Operator 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.

CodeTypical statusMeaningMethods that throw
GAME_NOT_FOUND404Game not found in the catalog.casino.getGame, casino.launchGame
SESSION_NOT_FOUND404Game session (at the provider) not found.casino session methods
PROVIDER_ERROR503Error at the casino provider: treat as unavailable.catalog and casino.launchGame
CASINO_UNAVAILABLE500Casino 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).

CodeTypical statusMeaningMethods that throw
BONUS_NOT_FOUND404Campaign, participation or promo code does not exist (or belongs to another player).bonus.getOffer, bonus.optIn, bonus.claim, bonus.resolvePromoCode, bonus.redeemPromoCode
BONUS_EXPIRED500Outside the joining or redemption window. The gateway does not map it yet: decide by code.bonus.optIn, bonus.claim, promo codes
BONUS_NOT_ELIGIBLE500The 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_CLAIMED409Reward 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).

CodeTypical statusMeaningMethods that throw
EVENT_NOT_FOUND500Event not found.markets.getEvent
MARKET_NOT_FOUND500Market not found.markets.getMarket and the market reads, orders.place, comments.list, comments.create
MARKET_NOT_OPEN500The market has not opened yet or has already closed.orders.place, orders.placeBatch
NO_LIQUIDITY500No liquidity to match the order.orders.place, orders.placeBatch
ORDER_NOT_FOUND500Order not found (or belongs to another player).orders.get, orders.cancel, orders.amend
COMMENT_NOT_FOUND500Comment not found.comments.like, comments.unlike

orders.place also throws INSUFFICIENT_BALANCE (see Financial and payments).

Compliance and responsible gaming ​

CodeTypical statusMeaningMethods that throw
KYC_REQUIRED422Identity verification (KYC) pending before the operation.withdrawal/deposit endpoints (outside this SDK)
KYC_PENDING422KYC submitted and under review.same
KYC_REJECTED500KYC rejected. The gateway's handleAppError does not map it either: it arrives as HTTP 500 with the code preserved.same
SELF_EXCLUDED422Player is self-excluded.login, casino.launchGame
COOLING_OFF500Player 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.

CodeMeaning
NETWORK_ERRORNetwork failure (fetch rejected): DNS, connection refused, CORS blocked, offline.
TIMEOUTThe request did not respond within timeoutMs.
ABORTEDThe app itself canceled the request via signal (AbortController). Same code the gateway can emit with an HTTP status — see the table Protocol generics.
VALIDATION_ERRORGateway 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_ERRORIncomplete 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.