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
| Code | What to show | Where 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 retry | login, launching a game |
KYC_REQUIRED | "Verify your identity to continue" with the button to the KYC screen | deposits.createPix, withdrawals.request/confirmOtp |
KYC_PENDING | "We are reviewing your documents"; no resubmission | operations that require KYC |
KYC_REJECTED | The reason (kyc.getStatus().rejectionReason) and the request to resubmit | operations 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 amount | sports 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.
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.
| Method | status | Re-read with | Then |
|---|---|---|---|
kyc.uploadDocument | 201 | kyc.getStatus() | only resubmit if the document does not appear |
loyalty.redeem | 200 | loyalty.get() | only repeat if the points were not deducted |
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:
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.