Errores de compliance
Cuando el jugador está en autoexclusión, con KYC pendiente o por encima de un límite, varias operaciones fallan con un código de compliance. Esta página dice qué mostrar en cada caso. La referencia completa de todos los códigos (status típico, métodos) está en Códigos de error; el formato de EnginexError en Errores.
Decide por el code, nunca por el status
Varios de estos códigos llegan como HTTP 500 (el gateway solo da una categoría propia a algunos errores del servicio de compliance). Los códigos parecidos no comparten status (p. ej., SELF_EXCLUDED es 422, mientras que COOLING_OFF y ACCOUNT_BLOCKED llegan como 500 al abrir un juego). Usa siempre isEnginexError(error, 'CODE').
Códigos y qué mostrar
| Código | Qué mostrar | Dónde aparece |
|---|---|---|
SELF_EXCLUDED | "Estás en autoexclusión." Sin acción de juego; enlace a ayuda y, si existe, la fecha en responsibleGambling.getLimits() | login, abrir un juego (casino) |
COOLING_OFF | "Estás en una pausa (cooling-off)." Indica el fin de la pausa (selfExclusion.until) | abrir un juego; puede aparecer también en apuestas (no verificado) |
ACCOUNT_BLOCKED | "Tu cuenta está bloqueada." Dirígelo a soporte; no reintentar | login, abrir un juego |
KYC_REQUIRED | "Verifica tu identidad para continuar" con el botón hacia la pantalla de KYC | deposits.createPix, withdrawals.request/confirmOtp |
KYC_PENDING | "Estamos revisando tus documentos"; sin reenvío | operaciones que exigen KYC |
KYC_REJECTED | El motivo (kyc.getStatus().rejectionReason) y la solicitud de reenvío | operaciones que exigen KYC |
DEPOSIT_LIMIT_EXCEEDED | "Alcanzaste tu límite de depósito" y cuánto queda (getLimits().deposit) | deposits.createPix |
BET_LIMIT_EXCEEDED | "Monto por encima del límite de apuesta"; pide un monto menor | apuestas deportivas |
WITHDRAWAL_LIMIT_EXCEEDED (retiro) sigue el mismo patrón que el depósito.
Qué está verificado
Solo la apertura de un juego (casino) está confirmada en el código como fallando con SELF_EXCLUDED, COOLING_OFF y ACCOUNT_BLOCKED. La columna "Dónde aparece" de los demás casos (depósito, retiro, apuesta) es lo que se espera del diseño del gateway y no fue verificado en el servicio de compliance.
Para la pantalla de KYC consulta Verificación de identidad; para límites y autoexclusión, Juego responsable.
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
}No muestres error.message tal cual: el texto viene del gateway, en inglés o sin contexto de producto. Muestra tu propio mensaje (y tradúcelo) a partir del code.
Operación no confirmada (UNKNOWN con status 2xx)
Regla única: UNKNOWN con status 2xx = operación no confirmada: vuelve a leer el estado antes de intentar de nuevo. El gateway respondió con éxito HTTP, pero sin confirmar la operación, así que puede haber ocurrido o no. El SDK nunca entrega un resultado como si hubiera salido bien. error.message es el mensaje del gateway cuando viene, si no el del SDK (kyc.uploadDocument: ..., loyalty.redeem: ...); decide siempre por code + status, no por el texto.
| Método | status | Vuelve a leer con | Después |
|---|---|---|---|
kyc.uploadDocument | 201 | kyc.getStatus() | reenvía solo si el documento no aparece |
loyalty.redeem | 200 | loyalty.get() | repite solo si no se descontaron los puntos |
function unconfirmed(error: unknown): boolean {
return isEnginexError(error, 'UNKNOWN') && error.status >= 200 && error.status < 300
}429 y retryAfter
Además de DEPOSIT_LIMIT_EXCEEDED (que también sale con status 429, pero es un límite del jugador, no de requests), el gateway tiene un limitador global de requests. Su 429 viene fuera del envelope ({ "error": "rate limit exceeded", "limit": 100, "reset_at": ..., "retry_after": 12 }) con el header Retry-After. El SDK lo convierte en un EnginexError con code: 'RESOURCE_EXHAUSTED', status: 429 y retryAfter en segundos:
try {
await enginex.kyc.getStatus()
} catch (e) {
if (isEnginexError(e, 'RESOURCE_EXHAUSTED')) {
setTimeout(retry, (e.retryAfter ?? 5) * 1000) // wait before trying again
}
}El SDK no repite el request por sí solo; lo decide la app. retryAfter viene del header Retry-After; sin el header, es undefined: usa un intervalo propio. No lo confundas con DEPOSIT_LIMIT_EXCEEDED: esperar no resuelve un límite del jugador.