Códigos de erro
Referência de todo code que um EnginexError pode trazer: os do gateway (GATEWAY_ERROR_CODES) e os que o próprio SDK gera sem resposta HTTP (SDK_ERROR_CODES). Veja Erros para o formato completo do EnginexError e como tratá-lo.
Sobre a caixa: a maioria dos códigos do gateway é SCREAMING_SNAKE_CASE, mas alguns endpoints mais novos (lookupCpf) espelham o gateway em snake_case minúsculo (ex.: captcha_required). O SDK nunca normaliza a caixa de code — trate a string exatamente como a tabela mostra.
ABORTED aparece nas duas listas (GATEWAY_ERROR_CODES e SDK_ERROR_CODES): o status diz quem o gerou. status: 0 é o SDK — o próprio app cancelou o request via signal, e normalmente pode ser ignorado; status diferente de 0 é o gateway, respondendo com um erro de negócio ABORTED (transação abortada no servidor), não um cancelamento.
if (isEnginexError(e, 'ABORTED') && e.status === 0) return // canceled by the app: ignoredetails vem cru do gateway (chaves como vieram no fio, sem camelCase) e é unknown por padrão. Só os códigos com details documentado abaixo têm entrada em ErrorDetailsMap — para eles, isEnginexError(e, code) estreita e.details automaticamente (veja details tipado); para os demais, faça sua própria checagem antes de usar o conteúdo.
Genéricos do protocolo
Sem um código de negócio específico, o gateway cai num destes pelo status HTTP.
| Código | Status típico | Significado | Métodos que lançam |
|---|---|---|---|
UNKNOWN | qualquer | Status sem mapeamento conhecido, ou erro não reconhecido pelo SDK (ex.: EnginexError.from com um valor sem code/message). Com status 2xx: operação não confirmada, releia o estado antes de tentar de novo (Erros de compliance). | qualquer método; 2xx em kyc.uploadDocument e loyalty.redeem |
INTERNAL_ERROR | 500 | Erro interno do gateway. | qualquer método |
INVALID_ARGUMENT | 400/422 ou 0 | Parâmetros inválidos no request. Com status: 0, o próprio SDK recusou antes de enviar: um id . ou .. no caminho (ex.: deposits.get({ depositId: '..' })), que a URL normalizaria para outra rota. | register, resetPassword, verifyPhone, confirmPhoneChange, config.get, métodos com id no caminho, outros |
NOT_FOUND | 404 | Recurso não encontrado. | qualquer método |
ALREADY_EXISTS | 409 | Recurso já existe (conflito). | qualquer método |
PERMISSION_DENIED | 403 | Sem permissão para o recurso. | qualquer método |
UNAUTHENTICATED | 401 | Sem sessão válida; também lançado pelo próprio SDK antes de enviar (sem chamar a rede) quando um método auth: 'required' é chamado sem sessão. | changePassword, requestPhoneChange, confirmPhoneChange, enable2fa, verify2fa, disable2fa, outros com sessão obrigatória |
RESOURCE_EXHAUSTED | 429 | Limite de uso atingido. | resendPhoneVerification, outros com rate limit |
FAILED_PRECONDITION | 412/422 | Pré-condição do servidor não satisfeita. | qualquer método |
ABORTED | 0 ou um status HTTP | Cancelamento: com status: 0, o próprio app cancelou o request via signal (normalmente pode ser ignorado); o gateway também pode emitir ABORTED com um status HTTP — nesse caso é um erro de negócio do servidor, não um cancelamento. | qualquer método (SDK, via signal), ou o gateway |
UNAVAILABLE | 502/503/504 | Gateway ou dependência fora do ar. | qualquer método |
Autenticação e conta
| Código | Status típico | Significado | Métodos que lançam |
|---|---|---|---|
INVALID_CREDENTIALS | 401 | E-mail/CPF ou senha incorretos. | login, changePassword, disable2fa |
ACCOUNT_LOCKED | 403 | Conta bloqueada temporariamente (ex.: excesso de tentativas). | login |
ACCOUNT_SUSPENDED | 403 | Conta suspensa pelo operador. | login |
ACCOUNT_BLOCKED | 403 | Conta bloqueada permanentemente. | login |
TOKEN_EXPIRED | 401 | Access token expirado; o SDK tenta renovar via refresh automaticamente antes de repassar isto ao app. | requests autenticados (raro chegar ao app) |
TOKEN_INVALID | 401 | Token malformado ou revogado; inclui o token de resetPassword/verifyEmail. | resetPassword, verifyEmail, requests autenticados |
SESSION_EXPIRED | 401 | Sessão expirada no gateway (refresh token também inválido). | requests autenticados |
2FA_REQUIRED | 428 | Login exige o código do app autenticador; o SDK nunca repassa isto como rejeição — login devolve { status: '2fa_required' }. | tratado internamente por login |
2FA_INVALID | 422 | Código 2FA incorreto ou expirado. | login, verify2fa, disable2fa |
Cadastro e verificação
| Código | Status típico | Significado | Métodos que lançam |
|---|---|---|---|
USER_NOT_FOUND | 404 | Usuário não encontrado. | qualquer método com userId |
EMAIL_ALREADY_EXISTS | 409 | E-mail já cadastrado. | register |
CPF_ALREADY_EXISTS | 409 | CPF já cadastrado. | register |
INVALID_CPF | 422 | CPF inválido (dígito verificador). | register |
INVALID_EMAIL | 422 | E-mail inválido. | register |
INVALID_PHONE | 422 | Telefone inválido. | register, requestPhoneChange |
PASSWORD_EXPIRED | 403 | Senha expirada; peça a troca antes de continuar. | login |
PASSWORD_SAME_AS_CURRENT | 422 | Nova senha igual à atual. | changePassword |
CPF e captcha (caixa mista, espelha o gateway)
Estes quatro vêm em snake_case minúsculo — não são SCREAMING_SNAKE_CASE como o resto da lista.
| Código | Status típico | Significado | details | Métodos que lançam |
|---|---|---|---|---|
captcha_required | 428 | Captcha obrigatório antes de repetir a chamada. | { site_key: string } (ou ausente) — tipado em ErrorDetailsMap como CaptchaRequiredDetails | undefined | lookupCpf |
rate_limited | 429 | Limite de chamadas à Receita atingido. | cru | lookupCpf |
cpf_already_registered | 409 | CPF já tem conta. | cru | lookupCpf |
cpf_validation_failed | 422 | CPF inválido ou não encontrado na Receita. | cru | lookupCpf |
Financeiro e pagamentos
Repassados do serviço de pagamento/carteira pelo gateway. O status é o que o handleAppError do gateway atribui: códigos sem categoria própria lá saem como 500, mesmo sendo erros de negócio — trate pelo code, nunca pelo status. Limites mínimo/máximo de depósito e saque da config não usam estes códigos: o gateway os recusa antes, com INVALID_ARGUMENT (400) e uma mensagem pronta (ex.: depósito mínimo é 10.00 BRL).
| Código | Status típico | Significado | Métodos que lançam |
|---|---|---|---|
INSUFFICIENT_BALANCE | 422 | Saldo insuficiente para a operação. | withdrawals.request (sem OTP), withdrawals.confirmOtp |
KYC_REQUIRED | 422 | Verificação de identidade pendente para movimentar dinheiro. | deposits.createPix, withdrawals.request, withdrawals.confirmOtp |
WITHDRAWAL_LIMIT_EXCEEDED | 429 | Limite de saque (jogo responsável/operador) excedido. | withdrawals.request (sem OTP), withdrawals.confirmOtp |
DEPOSIT_LIMIT_EXCEEDED | 429 | Limite de depósito (jogo responsável/operador) excedido. | deposits.createPix |
WITHDRAWAL_PENDING | 500 | Já existe um saque pendente. | withdrawals.request (sem OTP), withdrawals.confirmOtp |
PAYMENT_FAILED | 500 | Pagamento recusado pelo provedor. | deposits.createPix, withdrawals.request, withdrawals.confirmOtp |
PAYMENT_EXPIRED | 500 | Janela de pagamento expirou (ex.: PIX). | métodos de pagamento |
PAYMENT_CANCELLED | 500 | Pagamento cancelado pelo jogador ou pelo provedor. | métodos de pagamento |
RESERVATION_NOT_FOUND | 500 | Reserva de saldo não encontrada (expirada ou já confirmada). | produtos (apostas, cassino) |
RESERVATION_EXPIRED | 500 | Reserva de saldo expirou antes de confirmar. | produtos (apostas, cassino) |
DUPLICATE_TRANSACTION | 500 | Transação duplicada no serviço de carteira. | métodos que movimentam dinheiro |
TRANSACTION_FAILED | 500 | Transação falhou no serviço de carteira. | métodos que movimentam dinheiro |
Idempotência
Emitidos pelo middleware de idempotência do gateway nas rotas que movimentam dinheiro (deposits.createPix, withdrawals.request, withdrawals.confirmOtp, e as de produto). Veja Idempotência.
| Código | Status típico | Significado | O que fazer |
|---|---|---|---|
KEY_IN_USE | 409 | A mesma Idempotency-Key ainda está em processamento (outra aba, clique duplo). | Espere e repita com a mesma chave: recebe a resposta da primeira. |
PAYLOAD_MISMATCH | 422 | A chave já foi usada com outro corpo (outro valor, outra chave PIX). | Bug do app: gere uma chave nova por operação. |
INVALID_KEY | 400 | Chave com mais de 255 caracteres. | Use um UUID (crypto.randomUUID()). |
Apostas esportivas
| Código | Status típico | Significado |
|---|---|---|
BET_NOT_FOUND | 404 | Aposta não encontrada. |
BET_CLOSED | 422 | Mercado fechado para a aposta. |
ODDS_CHANGED | 409 | Odd mudou entre a cotação e a confirmação. |
CASHOUT_UNAVAILABLE | 422 | Cashout indisponível para esta aposta. |
BET_LIMIT_EXCEEDED | 422 | Limite de aposta do operador excedido. |
Nenhum método do SDK lança estes hoje: o sportsbook (FIRST) roda no próprio quadro (veja Sportsbook (FIRST)). Estão listados porque o gateway os define.
Cassino
Lançados por igaming.casino (Cassino e abrir jogo). O gateway não mapeia todo código para um status próprio: decida pelo code.
| Código | Status típico | Significado | Métodos que lançam |
|---|---|---|---|
GAME_NOT_FOUND | 404 | Jogo não encontrado no catálogo. | casino.getGame, casino.launchGame |
SESSION_NOT_FOUND | 404 | Sessão de jogo (no provedor) não encontrada. | métodos de sessão do cassino |
PROVIDER_ERROR | 503 | Erro no provedor de cassino: trate como indisponível. | catálogo e casino.launchGame |
CASINO_UNAVAILABLE | 500 | Cassino indisponível (provedor ou operador): trate como indisponível. | catálogo e casino.launchGame |
casino.launchGame também lança SELF_EXCLUDED e COOLING_OFF (veja Compliance e jogo responsável).
Bônus
Lançados por igaming.bonus (Bônus e promo codes).
| Código | Status típico | Significado | Métodos que lançam |
|---|---|---|---|
BONUS_NOT_FOUND | 404 | Campanha, participação ou promo code não existe (ou é de outro jogador). | bonus.getOffer, bonus.optIn, bonus.claim, bonus.resolvePromoCode, bonus.redeemPromoCode |
BONUS_EXPIRED | 500 | Fora da janela de entrada ou de resgate. O gateway ainda não o mapeia: decida pelo code. | bonus.optIn, bonus.claim, promo codes |
BONUS_NOT_ELIGIBLE | 500 | O jogador não pode entrar nem resgatar (ex.: ainda não se qualificou). O gateway ainda não o mapeia: decida pelo code. | bonus.optIn, bonus.claim, promo codes |
BONUS_ALREADY_CLAIMED | 409 | Recompensa já resgatada; promo code já usado. | bonus.optIn, bonus.claim, bonus.redeemPromoCode |
Predictions
Lançados por @getenginex/sdk-predictions. O gateway ainda não mapeia estes códigos para um status próprio: eles chegam com HTTP 500. Decida sempre pelo code (Ordens).
| Código | Status típico | Significado | Métodos que lançam |
|---|---|---|---|
EVENT_NOT_FOUND | 500 | Evento não encontrado. | markets.getEvent |
MARKET_NOT_FOUND | 500 | Mercado não encontrado. | markets.getMarket e as leituras do mercado, orders.place, comments.list, comments.create |
MARKET_NOT_OPEN | 500 | O mercado ainda não abriu ou já fechou. | orders.place, orders.placeBatch |
NO_LIQUIDITY | 500 | Sem liquidez para casar a ordem. | orders.place, orders.placeBatch |
ORDER_NOT_FOUND | 500 | Ordem não encontrada (ou de outro jogador). | orders.get, orders.cancel, orders.amend |
COMMENT_NOT_FOUND | 500 | Comentário não encontrado. | comments.like, comments.unlike |
orders.place também lança INSUFFICIENT_BALANCE (veja Financeiro e pagamentos).
Compliance e jogo responsável
| Código | Status típico | Significado | Métodos que lançam |
|---|---|---|---|
KYC_REQUIRED | 422 | Verificação de identidade (KYC) pendente antes da operação. | endpoints de saque/depósito (fora deste SDK) |
KYC_PENDING | 422 | KYC enviado e em análise. | idem |
KYC_REJECTED | 500 | KYC rejeitado. O handleAppError do gateway também não o mapeia: chega como HTTP 500 com o code preservado. | idem |
SELF_EXCLUDED | 422 | Jogador em autoexclusão. | login, casino.launchGame |
COOLING_OFF | 500 | Jogador em período de cooling-off. O handleAppError do gateway não mapeia este código: chega como HTTP 500 com o code preservado. | abrir jogo (cassino); decida por code |
Códigos do SDK (sem resposta HTTP do gateway)
status é sempre 0 nestes — não houve resposta HTTP.
| Código | Significado |
|---|---|
NETWORK_ERROR | Falha de rede (fetch rejeitou): DNS, conexão recusada, CORS bloqueado, offline. |
TIMEOUT | O request não respondeu dentro de timeoutMs. |
ABORTED | O próprio app cancelou o request via signal (AbortController). Mesmo código que o gateway pode emitir com um status HTTP — veja a tabela Genéricos do protocolo. |
VALIDATION_ERROR | Resposta do gateway fora do schema esperado, em modo 'strict' (ou, em 'warn', com a própria raiz fora do formato; veja Validação de respostas); ou uma resposta 2xx que passou no schema mas falhou numa checagem pós-resposta (ex.: login sem 2FA que voltou sem tokens). |
CONFIGURATION_ERROR | Configuração do cliente incompleta ou ausente: baseUrl/tenantHost/fetch não resolvidos (veja Next.js / SSR); ou o cliente foi descartado com client.dispose(). |
Códigos novos que o SDK ainda não conhece
EnginexErrorCode aceita qualquer string (KnownErrorCode | (string & {})), então isEnginexError funciona também para códigos novos que o gateway venha a emitir antes do SDK os conhecer — o autocomplete sugere os códigos acima, mas não impede outros.