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ódigo | O que mostrar | Onde 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 novo | login, abrir jogo |
KYC_REQUIRED | "Verifique sua identidade para continuar" com o botão para a tela de KYC | deposits.createPix, withdrawals.request/confirmOtp |
KYC_PENDING | "Estamos analisando seus documentos"; sem reenvio | operações que exigem KYC |
KYC_REJECTED | O motivo (kyc.getStatus().rejectionReason) e o pedido de reenvio | operaçõ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 menor | apostas 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.
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étodo | status | Releia com | Depois |
|---|---|---|---|
kyc.uploadDocument | 201 | kyc.getStatus() | só reenvie se o documento não aparece |
loyalty.redeem | 200 | loyalty.get() | só repita se os pontos não foram descontados |
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:
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.