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

Erros de compliance ​

Quando o jogador está em autoexclusão, com KYC pendente ou acima de um limite, várias operações falham com um código de compliance. Esta página diz o que mostrar em cada caso. A referência completa de todos os códigos (status típico, métodos) está em Códigos de erro; o formato do EnginexError em Erros.

Decida pelo code, nunca pelo status

Vários destes códigos chegam como HTTP 500 (o gateway só dá categoria própria a alguns erros do serviço de compliance). Códigos parecidos não compartilham status (ex.: SELF_EXCLUDED é 422, enquanto COOLING_OFF e ACCOUNT_BLOCKED chegam como 500 ao abrir um jogo). Use sempre isEnginexError(error, 'CODE').

Códigos e o que mostrar ​

CódigoO que mostrarOnde aparece
SELF_EXCLUDED"Você está em autoexclusão." Sem ação de jogo; link para ajuda e, se houver, a data em responsibleGambling.getLimits()login, abrir jogo (cassino)
COOLING_OFF"Você está em uma pausa (cooling-off)." Informe o fim da pausa (selfExclusion.until)abrir jogo; pode aparecer também em apostas (não verificado)
ACCOUNT_BLOCKED"Sua conta está bloqueada." Oriente a falar com o suporte; não tente de novologin, abrir jogo
KYC_REQUIRED"Verifique sua identidade para continuar" com o botão para a tela de KYCdeposits.createPix, withdrawals.request/confirmOtp
KYC_PENDING"Estamos analisando seus documentos"; sem reenviooperações que exigem KYC
KYC_REJECTEDO motivo (kyc.getStatus().rejectionReason) e o pedido de reenviooperações que exigem KYC
DEPOSIT_LIMIT_EXCEEDED"Você atingiu seu limite de depósito" e o quanto resta (getLimits().deposit)deposits.createPix
BET_LIMIT_EXCEEDED"Valor acima do limite de aposta"; peça um valor menorapostas esportivas

WITHDRAWAL_LIMIT_EXCEEDED (saque) segue o mesmo padrão do depósito.

O que está verificado

Só a abertura de jogo (cassino) está confirmada no código como falhando com SELF_EXCLUDED, COOLING_OFF e ACCOUNT_BLOCKED. A coluna "Onde aparece" dos demais casos (depósito, saque, aposta) é o que se espera do desenho do gateway e não foi verificado no serviço de compliance.

Para a tela de KYC veja Verificação de identidade; para limites e autoexclusão, Jogo responsável.

ts
import { isEnginexError } from '@getenginex/sdk'

function complianceMessage(error: unknown): string | undefined {
  if (isEnginexError(error, 'SELF_EXCLUDED')) return 'You are self-excluded.'
  if (isEnginexError(error, 'COOLING_OFF')) return 'You are in a cooling-off period.'
  if (isEnginexError(error, 'ACCOUNT_BLOCKED')) return 'Your account is blocked. Contact support.'
  if (isEnginexError(error, 'KYC_REQUIRED')) return 'Verify your identity to continue.'
  if (isEnginexError(error, 'KYC_PENDING')) return 'We are reviewing your documents.'
  if (isEnginexError(error, 'KYC_REJECTED')) return 'Your verification was rejected. Submit the documents again.'
  if (isEnginexError(error, 'DEPOSIT_LIMIT_EXCEEDED')) return 'You have reached your deposit limit.'
  if (isEnginexError(error, 'BET_LIMIT_EXCEEDED')) return 'Amount above the bet limit.'
  return undefined // not a compliance error: handle it as a generic error
}

Não mostre error.message como está: o texto vem do gateway, em inglês ou sem contexto de produto. Mostre a sua mensagem (e traduza) a partir do code.

Operação não confirmada (UNKNOWN com status 2xx) ​

Regra única: UNKNOWN com status 2xx = operação não confirmada: releia o estado antes de tentar de novo. O gateway respondeu com sucesso HTTP, mas sem confirmar a operação, então ela pode ter acontecido ou não. O SDK nunca entrega um resultado como se tivesse dado certo. error.message é a mensagem do gateway quando ela vem, senão a do SDK (kyc.uploadDocument: ..., loyalty.redeem: ...); decida sempre pelo code + status, não pelo texto.

MétodostatusReleia comDepois
kyc.uploadDocument201kyc.getStatus()só reenvie se o documento não aparece
loyalty.redeem200loyalty.get()só repita se os pontos não foram descontados
ts
function unconfirmed(error: unknown): boolean {
  return isEnginexError(error, 'UNKNOWN') && error.status >= 200 && error.status < 300
}

429 e retryAfter ​

Além do DEPOSIT_LIMIT_EXCEEDED (que também sai com status 429, mas é um limite do jogador, não de requisições), o gateway tem um limitador global de requisições. O 429 dele vem fora do envelope ({ "error": "rate limit exceeded", "limit": 100, "reset_at": ..., "retry_after": 12 }) com o header Retry-After. O SDK o converte em EnginexError com code: 'RESOURCE_EXHAUSTED', status: 429 e retryAfter em segundos:

ts
try {
  await enginex.kyc.getStatus()
} catch (e) {
  if (isEnginexError(e, 'RESOURCE_EXHAUSTED')) {
    setTimeout(retry, (e.retryAfter ?? 5) * 1000) // wait before trying again
  }
}

O SDK não repete o request sozinho; quem decide é o app. retryAfter vem do header Retry-After; sem o header, é undefined: use um intervalo próprio. Não confunda com DEPOSIT_LIMIT_EXCEEDED: esperar não resolve um limite do jogador.