This version (v0.7) has not been published to npm yet.
Skip to content

Compliance errors ​

When the player is self-excluded, has pending KYC or is over a limit, several operations fail with a compliance code. This page tells you what to show in each case. The complete reference of all codes (typical status, methods) is in Error codes; the format of EnginexError is in Errors.

Decide by code, never by status

Several of these codes arrive as HTTP 500 (the gateway only gives its own category to some errors from the compliance service). Related codes do not share a status (e.g. SELF_EXCLUDED is 422, while COOLING_OFF and ACCOUNT_BLOCKED arrive as 500 when launching a game). Always use isEnginexError(error, 'CODE').

Codes and what to show ​

CodeWhat to showWhere it appears
SELF_EXCLUDED"You are self-excluded." No gaming action; link to help and, if there is one, the date in responsibleGambling.getLimits()login, launching a game (casino)
COOLING_OFF"You are in a cooling-off period." Show when the pause ends (selfExclusion.until)launching a game; may also appear on bets (not verified)
ACCOUNT_BLOCKED"Your account is blocked." Direct them to contact support; do not retrylogin, launching a game
KYC_REQUIRED"Verify your identity to continue" with the button to the KYC screendeposits.createPix, withdrawals.request/confirmOtp
KYC_PENDING"We are reviewing your documents"; no resubmissionoperations that require KYC
KYC_REJECTEDThe reason (kyc.getStatus().rejectionReason) and the request to resubmitoperations that require KYC
DEPOSIT_LIMIT_EXCEEDED"You have reached your deposit limit" and how much remains (getLimits().deposit)deposits.createPix
BET_LIMIT_EXCEEDED"Amount above the bet limit"; ask for a smaller amountsports bets

WITHDRAWAL_LIMIT_EXCEEDED (withdrawal) follows the same pattern as the deposit.

What is verified

Only launching a game (casino) is confirmed in the code as failing with SELF_EXCLUDED, COOLING_OFF and ACCOUNT_BLOCKED. The "Where it appears" column for the other cases (deposit, withdrawal, bet) is what is expected from the gateway's design and was not verified in the compliance service.

For the KYC screen see Identity verification; for limits and self-exclusion, Responsible gaming.

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
}

Do not show error.message as is: the text comes from the gateway, in English or without product context. Show your own message (and translate it) based on the code.

Unconfirmed operation (UNKNOWN with a 2xx status) ​

A single rule: UNKNOWN with a 2xx status = unconfirmed operation: re-read the state before trying again. The gateway responded with HTTP success, but without confirming the operation, so it may have happened or not. The SDK never delivers a result as if it had succeeded. error.message is the gateway's message when it comes, otherwise the SDK's (kyc.uploadDocument: ..., loyalty.redeem: ...); always decide by code + status, not by the text.

MethodstatusRe-read withThen
kyc.uploadDocument201kyc.getStatus()only resubmit if the document does not appear
loyalty.redeem200loyalty.get()only repeat if the points were not deducted
ts
function unconfirmed(error: unknown): boolean {
  return isEnginexError(error, 'UNKNOWN') && error.status >= 200 && error.status < 300
}

429 and retryAfter ​

Besides DEPOSIT_LIMIT_EXCEEDED (which also comes out with status 429, but is a limit on the player, not on requests), the gateway has a global request limiter. Its 429 comes outside the envelope ({ "error": "rate limit exceeded", "limit": 100, "reset_at": ..., "retry_after": 12 }) with the Retry-After header. The SDK converts it into an EnginexError with code: 'RESOURCE_EXHAUSTED', status: 429 and retryAfter in seconds:

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

The SDK does not repeat the request on its own; the app decides. retryAfter comes from the Retry-After header; without the header, it is undefined: use an interval of your own. Do not confuse it with DEPOSIT_LIMIT_EXCEEDED: waiting does not resolve a player limit.