Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

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.

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

details 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ódigoStatus típicoSignificadoMétodos que lançam
UNKNOWNqualquerStatus 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_ERROR500Erro interno do gateway.qualquer método
INVALID_ARGUMENT400/422 ou 0Parâ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_FOUND404Recurso não encontrado.qualquer método
ALREADY_EXISTS409Recurso já existe (conflito).qualquer método
PERMISSION_DENIED403Sem permissão para o recurso.qualquer método
UNAUTHENTICATED401Sem 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_EXHAUSTED429Limite de uso atingido.resendPhoneVerification, outros com rate limit
FAILED_PRECONDITION412/422Pré-condição do servidor não satisfeita.qualquer método
ABORTED0 ou um status HTTPCancelamento: 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
UNAVAILABLE502/503/504Gateway ou dependência fora do ar.qualquer método

Autenticação e conta ​

CódigoStatus típicoSignificadoMétodos que lançam
INVALID_CREDENTIALS401E-mail/CPF ou senha incorretos.login, changePassword, disable2fa
ACCOUNT_LOCKED403Conta bloqueada temporariamente (ex.: excesso de tentativas).login
ACCOUNT_SUSPENDED403Conta suspensa pelo operador.login
ACCOUNT_BLOCKED403Conta bloqueada permanentemente.login
TOKEN_EXPIRED401Access token expirado; o SDK tenta renovar via refresh automaticamente antes de repassar isto ao app.requests autenticados (raro chegar ao app)
TOKEN_INVALID401Token malformado ou revogado; inclui o token de resetPassword/verifyEmail.resetPassword, verifyEmail, requests autenticados
SESSION_EXPIRED401Sessão expirada no gateway (refresh token também inválido).requests autenticados
2FA_REQUIRED428Login 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_INVALID422Código 2FA incorreto ou expirado.login, verify2fa, disable2fa

Cadastro e verificação ​

CódigoStatus típicoSignificadoMétodos que lançam
USER_NOT_FOUND404Usuário não encontrado.qualquer método com userId
EMAIL_ALREADY_EXISTS409E-mail já cadastrado.register
CPF_ALREADY_EXISTS409CPF já cadastrado.register
INVALID_CPF422CPF inválido (dígito verificador).register
INVALID_EMAIL422E-mail inválido.register
INVALID_PHONE422Telefone inválido.register, requestPhoneChange
PASSWORD_EXPIRED403Senha expirada; peça a troca antes de continuar.login
PASSWORD_SAME_AS_CURRENT422Nova 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ódigoStatus típicoSignificadodetailsMétodos que lançam
captcha_required428Captcha obrigatório antes de repetir a chamada.{ site_key: string } (ou ausente) — tipado em ErrorDetailsMap como CaptchaRequiredDetails | undefinedlookupCpf
rate_limited429Limite de chamadas à Receita atingido.crulookupCpf
cpf_already_registered409CPF já tem conta.crulookupCpf
cpf_validation_failed422CPF inválido ou não encontrado na Receita.crulookupCpf

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ódigoStatus típicoSignificadoMétodos que lançam
INSUFFICIENT_BALANCE422Saldo insuficiente para a operação.withdrawals.request (sem OTP), withdrawals.confirmOtp
KYC_REQUIRED422Verificação de identidade pendente para movimentar dinheiro.deposits.createPix, withdrawals.request, withdrawals.confirmOtp
WITHDRAWAL_LIMIT_EXCEEDED429Limite de saque (jogo responsável/operador) excedido.withdrawals.request (sem OTP), withdrawals.confirmOtp
DEPOSIT_LIMIT_EXCEEDED429Limite de depósito (jogo responsável/operador) excedido.deposits.createPix
WITHDRAWAL_PENDING500Já existe um saque pendente.withdrawals.request (sem OTP), withdrawals.confirmOtp
PAYMENT_FAILED500Pagamento recusado pelo provedor.deposits.createPix, withdrawals.request, withdrawals.confirmOtp
PAYMENT_EXPIRED500Janela de pagamento expirou (ex.: PIX).métodos de pagamento
PAYMENT_CANCELLED500Pagamento cancelado pelo jogador ou pelo provedor.métodos de pagamento
RESERVATION_NOT_FOUND500Reserva de saldo não encontrada (expirada ou já confirmada).produtos (apostas, cassino)
RESERVATION_EXPIRED500Reserva de saldo expirou antes de confirmar.produtos (apostas, cassino)
DUPLICATE_TRANSACTION500Transação duplicada no serviço de carteira.métodos que movimentam dinheiro
TRANSACTION_FAILED500Transaçã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ódigoStatus típicoSignificadoO que fazer
KEY_IN_USE409A mesma Idempotency-Key ainda está em processamento (outra aba, clique duplo).Espere e repita com a mesma chave: recebe a resposta da primeira.
PAYLOAD_MISMATCH422A chave já foi usada com outro corpo (outro valor, outra chave PIX).Bug do app: gere uma chave nova por operação.
INVALID_KEY400Chave com mais de 255 caracteres.Use um UUID (crypto.randomUUID()).

Apostas esportivas ​

CódigoStatus típicoSignificado
BET_NOT_FOUND404Aposta não encontrada.
BET_CLOSED422Mercado fechado para a aposta.
ODDS_CHANGED409Odd mudou entre a cotação e a confirmação.
CASHOUT_UNAVAILABLE422Cashout indisponível para esta aposta.
BET_LIMIT_EXCEEDED422Limite 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ódigoStatus típicoSignificadoMétodos que lançam
GAME_NOT_FOUND404Jogo não encontrado no catálogo.casino.getGame, casino.launchGame
SESSION_NOT_FOUND404Sessão de jogo (no provedor) não encontrada.métodos de sessão do cassino
PROVIDER_ERROR503Erro no provedor de cassino: trate como indisponível.catálogo e casino.launchGame
CASINO_UNAVAILABLE500Cassino 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ódigoStatus típicoSignificadoMétodos que lançam
BONUS_NOT_FOUND404Campanha, participação ou promo code não existe (ou é de outro jogador).bonus.getOffer, bonus.optIn, bonus.claim, bonus.resolvePromoCode, bonus.redeemPromoCode
BONUS_EXPIRED500Fora 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_ELIGIBLE500O 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_CLAIMED409Recompensa 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ódigoStatus típicoSignificadoMétodos que lançam
EVENT_NOT_FOUND500Evento não encontrado.markets.getEvent
MARKET_NOT_FOUND500Mercado não encontrado.markets.getMarket e as leituras do mercado, orders.place, comments.list, comments.create
MARKET_NOT_OPEN500O mercado ainda não abriu ou já fechou.orders.place, orders.placeBatch
NO_LIQUIDITY500Sem liquidez para casar a ordem.orders.place, orders.placeBatch
ORDER_NOT_FOUND500Ordem não encontrada (ou de outro jogador).orders.get, orders.cancel, orders.amend
COMMENT_NOT_FOUND500Comentá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ódigoStatus típicoSignificadoMétodos que lançam
KYC_REQUIRED422Verificação de identidade (KYC) pendente antes da operação.endpoints de saque/depósito (fora deste SDK)
KYC_PENDING422KYC enviado e em análise.idem
KYC_REJECTED500KYC rejeitado. O handleAppError do gateway também não o mapeia: chega como HTTP 500 com o code preservado.idem
SELF_EXCLUDED422Jogador em autoexclusão.login, casino.launchGame
COOLING_OFF500Jogador 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ódigoSignificado
NETWORK_ERRORFalha de rede (fetch rejeitou): DNS, conexão recusada, CORS bloqueado, offline.
TIMEOUTO request não respondeu dentro de timeoutMs.
ABORTEDO 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_ERRORResposta 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_ERRORConfiguraçã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.