Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

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ódigoQué mostrarDó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 reintentarlogin, abrir un juego
KYC_REQUIRED"Verifica tu identidad para continuar" con el botón hacia la pantalla de KYCdeposits.createPix, withdrawals.request/confirmOtp
KYC_PENDING"Estamos revisando tus documentos"; sin reenvíooperaciones que exigen KYC
KYC_REJECTEDEl motivo (kyc.getStatus().rejectionReason) y la solicitud de reenvíooperaciones 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 menorapuestas 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.

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
}

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étodostatusVuelve a leer conDespués
kyc.uploadDocument201kyc.getStatus()reenvía solo si el documento no aparece
loyalty.redeem200loyalty.get()repite solo si no se descontaron los puntos
ts
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:

ts
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.